Merge pull request 'chore(ci): 프론트 PR #23~#39를 합친 트리를 한 번에 검사하고 병합한다' (#40) from claude/r9-fe-combined-check into main
frontend-quality-gates / merge / static checks (push) Successful in 1m56s
frontend-quality-gates / merge / tests (push) Successful in 13m57s
frontend-quality-gates / merge / browser tests (push) Successful in 6m34s
frontend-quality-gates / FE-GATE-014 / config-compatibility (push) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (push) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (push) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (push) Skipped
frontend-quality-gates / external-vulnerability-provider (push) Skipped
frontend-quality-gates / external-provenance-provider (push) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (push) Skipped
frontend-quality-gates / deploy-promoted-release (push) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (push) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (push) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (push) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (push) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (push) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (push) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (push) Skipped
frontend-quality-gates / FE-GATE-017 / diagram-review (push) Skipped
frontend-quality-gates / main / self-tests and removal drills (push) Successful in 7m52s
frontend-quality-gates / merge / static checks (push) Successful in 1m56s
frontend-quality-gates / merge / tests (push) Successful in 13m57s
frontend-quality-gates / merge / browser tests (push) Successful in 6m34s
frontend-quality-gates / FE-GATE-014 / config-compatibility (push) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (push) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (push) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (push) Skipped
frontend-quality-gates / external-vulnerability-provider (push) Skipped
frontend-quality-gates / external-provenance-provider (push) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (push) Skipped
frontend-quality-gates / deploy-promoted-release (push) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (push) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (push) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (push) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (push) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (push) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (push) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (push) Skipped
frontend-quality-gates / FE-GATE-017 / diagram-review (push) Skipped
frontend-quality-gates / main / self-tests and removal drills (push) Successful in 7m52s
This commit was merged in pull request #40.
This commit is contained in:
@@ -19,5 +19,5 @@ paths:
|
||||
- 기준선 기록(초기 JS, 기능 모양)은 손으로 고치지 않는다. 측정 스크립트를 `--initial-baseline --write`로 돌린 결과를 같은 변경에 넣는다.
|
||||
- workflow는 생성기로 만든다. `.gitea/workflows/`만 손으로 고치지 않는다(`check:ci`가 대조한다).
|
||||
- 새 검사에는 통과 fixture와 거절 fixture를 함께 둔다. 실패 메시지는 넘은 항목·잰 값·고칠 파일을 말한다. 사전 점검은 본 단계와 같은 방법으로 한 번 실행해 본다.
|
||||
- 바꾼 뒤 desktop에서 `scripts/verify.sh merge`. stage·게이트 목록이 바뀌어도 `scripts/verify.sh`는 계약 파일에서 읽어 따라간다.
|
||||
- 편집 훅(N6)이 이 파일들의 편집을 알린다. 알림은 막지 않는다. 의도한 변경이면 커밋 본문에 이유와 결정 출처를 적는다.
|
||||
- 바꾼 뒤 desktop에서 `scripts/verify.sh merge`. 검사 script나 그 fixture를 바꿨으면 `scripts/verify.sh gate FE-GATE-029`도 돌린다(검사기 자기 시험은 main 단계다). stage·게이트 목록이 바뀌어도 `scripts/verify.sh`는 계약 파일에서 읽어 따라간다.
|
||||
- 편집 훅(N6)이 예산·기준선·ungated 목록·시험 설정·스냅숏의 편집을 알린다(목록은 `scripts/hooks/README.md`). 이 규칙의 다른 파일(`config/ci/gates.json`, workflow, 검사 script)은 알리지 않는다. 알림은 막지 않는다. 의도한 변경이면 커밋 본문에 이유와 결정 출처를 적는다.
|
||||
|
||||
@@ -18,8 +18,8 @@ paths:
|
||||
6. 가끔 떨어지는 테스트를 재시도·timeout 늘리기·worker 줄이기·`force` 클릭으로 덮지 않는다. 반복 실행 → 실패 기록 → 결정적 재현 → 수정 → 변이 순서로 원인을 찾는다.
|
||||
7. 환경에 기대지 않는다: gitignore된 생성물, 작성자 PC의 글꼴·CPU, 바깥 env(`CI=true`, 빌드 식별값). 테스트가 띄우는 빌드·서버의 env는 테스트가 정한다.
|
||||
8. 플랫폼 테스트를 기능·스타터 화면에 묶지 않는다(테스트 전용 라우트, `tests/mocks/`). 테스트가 지워도 되는 문서(`docs/reviews/` 등)를 읽지 않는다.
|
||||
9. 자식 프로세스를 띄우는 suite는 자기 timeout을 선언한다. 전역 timeout을 올리지 않는다.
|
||||
9. 자식 프로세스를 띄우는 suite는 자기 timeout을 선언한다. 전역 timeout을 올리지 않는다. 기본값보다 긴 timeout은 `childProcessTimeout(<desktop에서 잰 가장 긴 ms>)`로만 준다(손 숫자는 `tests/unit/test-timeout-declarations.test.ts`가 거절).
|
||||
|
||||
## 돌리는 법
|
||||
|
||||
- 노트북에서는 돌리지 않는다. 한 파일도 desktop에서: `scripts/verify.sh script test:unit`, 또는 `ssh desktop`으로 `node scripts/run-vitest.ts run <file>`(이 runner가 생성물을 먼저 만든다. `pnpm exec vitest run <file>`은 import 오류로 실패한다).
|
||||
- 노트북에서는 돌리지 않는다. 한 파일도 desktop에서 `scripts/verify.sh exec -- node scripts/run-vitest.ts run <file>`로 돌린다(이 runner가 생성물을 먼저 만든다. `pnpm exec vitest run <file>`은 import 오류로 실패한다). 실행 위치의 정본은 `docs/work/operate.md` 4.1절이다.
|
||||
|
||||
@@ -23,7 +23,7 @@ paths:
|
||||
|
||||
## 함정
|
||||
|
||||
1. axe 통과를 접근성 완료로 적는다. e2e 스캔의 태그는 `wcag2a`·`wcag2aa`·`wcag21a`·`wcag21aa`뿐이다. WCAG 2.2에서 더해진 기준(포커스가 가려지지 않음, 목표 크기 최소, 드래그 대안 등)은 자동으로 보지 않는다. 그리고 critical·serious 위반만 막는다. — `tests/e2e/accessibility.spec.ts`, `docs/accessibility/manual-checklist.md`, `docs/design/2026-07-26-design-system-platform-design.md` 13절
|
||||
1. axe 통과를 접근성 완료로 적는다. 스캔 태그는 `tests/support/browser/axe-tags.ts` 하나다. WCAG 2.2 AA 태그(`wcag22aa`, 목표 크기 2.5.8)도 돌지만, 2.2에서 더해진 기준 대부분(포커스가 가려지지 않음, 드래그 대안 등)은 axe에 규칙이 없어 자동으로 보지 않는다. 그리고 critical·serious 위반만 막는다. — `tests/e2e/accessibility.spec.ts`, `docs/accessibility/manual-checklist.md`, `docs/design/2026-07-26-design-system-platform-design.md` 13절
|
||||
2. 자동 스캔이 본 상태를 넘겨 짐작한다. 보호 라우트는 데모 로그인 뒤, 목록은 빈 상태, 단건 읽기 상세는 실패 상태에서 스캔하고 `notChecked`로 남긴다. 데이터가 찬 목록·상세는 기능 시험과 수동 검토 몫이다. — `docs/accessibility/manual-checklist.md` 「자동 실행이 검사하는 것」
|
||||
3. 린트가 의미를 잡아 줄 거라 믿는다. `eslint.config.ts`에 접근성 규칙 플러그인이 없다. `div` + 키 핸들러로 만든 버튼, 이름 없는 아이콘 버튼은 component 시험·axe·리뷰가 잡는다. — `eslint.config.ts`, `docs/design/2026-07-26-design-system-platform-design.md` 13절
|
||||
4. 저장 중 버튼을 `disabled`로 바꿔 키보드 포커스를 잃게 한다. `pending`을 쓴다. — `docs/manual/02-decision-tables.md` 6절
|
||||
|
||||
@@ -82,7 +82,7 @@ jobs:
|
||||
name: "merge / tests"
|
||||
if: ${{ gitea.event_name != 'workflow_dispatch' || (inputs.stage != 'documentation' && inputs.stage != 'main') }}
|
||||
# FE-GATE-013 runner requirement: Linux with executable /usr/bin/bwrap (with --size), /usr/bin/prlimit, /usr/bin/systemd-run, /usr/bin/systemctl and /usr/bin/tar, an active systemd user manager 254 or newer, and unified cgroup v2 with delegated memory, pids and cpu controllers
|
||||
# FE-GATE-013 runner requirement: unprivileged user and network namespaces for bwrap (the provider sandbox runs bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net); Ubuntu 23.10 and later refuse them while kernel.apparmor_restrict_unprivileged_userns=1 unless /usr/bin/bwrap has an AppArmor profile that allows userns; scripts/check-system-test-prerequisites.ts probes this before test:system runs
|
||||
# FE-GATE-013 runner requirement: unprivileged user and network namespaces for bwrap (the provider sandbox runs bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net); Ubuntu 23.10 and later refuse them while kernel.apparmor_restrict_unprivileged_userns=1 unless /usr/bin/bwrap has an AppArmor profile that allows userns; scripts/check-system-test-prerequisites.ts probes this before test:system runs and scripts/run-and-validate-provider.ts before a provider runs
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 45
|
||||
steps:
|
||||
@@ -303,6 +303,8 @@ jobs:
|
||||
vulnerability_provider:
|
||||
name: external-vulnerability-provider
|
||||
needs: immutable_build
|
||||
# provider sandbox runner requirement: Linux with executable /usr/bin/bwrap (with --size), /usr/bin/prlimit, /usr/bin/systemd-run, /usr/bin/systemctl and /usr/bin/tar, an active systemd user manager 254 or newer, and unified cgroup v2 with delegated memory, pids and cpu controllers
|
||||
# provider sandbox runner requirement: unprivileged user and network namespaces for bwrap (the provider sandbox runs bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net); Ubuntu 23.10 and later refuse them while kernel.apparmor_restrict_unprivileged_userns=1 unless /usr/bin/bwrap has an AppArmor profile that allows userns; scripts/check-system-test-prerequisites.ts probes this before test:system runs and scripts/run-and-validate-provider.ts before a provider runs
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 45
|
||||
outputs:
|
||||
@@ -349,6 +351,8 @@ jobs:
|
||||
provenance_provider:
|
||||
name: external-provenance-provider
|
||||
needs: immutable_build
|
||||
# provider sandbox runner requirement: Linux with executable /usr/bin/bwrap (with --size), /usr/bin/prlimit, /usr/bin/systemd-run, /usr/bin/systemctl and /usr/bin/tar, an active systemd user manager 254 or newer, and unified cgroup v2 with delegated memory, pids and cpu controllers
|
||||
# provider sandbox runner requirement: unprivileged user and network namespaces for bwrap (the provider sandbox runs bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net); Ubuntu 23.10 and later refuse them while kernel.apparmor_restrict_unprivileged_userns=1 unless /usr/bin/bwrap has an AppArmor profile that allows userns; scripts/check-system-test-prerequisites.ts probes this before test:system runs and scripts/run-and-validate-provider.ts before a provider runs
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 45
|
||||
outputs:
|
||||
|
||||
@@ -26,7 +26,7 @@
|
||||
|
||||
- 진입점은 `scripts/verify.sh <단계>`다. 단계는 `config/ci/gates.json`의 stage id(`merge` 등), 게이트 하나는 `scripts/verify.sh gate FE-GATE-005`(안에서 `corepack pnpm ci:gate FE-GATE-005`). pnpm 단계는 desktop으로 옮겨 돈다.
|
||||
- "merge 가능"은 merge 단계 게이트 전부를 `CI=true`로 돌려 통과한 것이다. 골라 돌린 결과로 말하지 않는다. FE-GATE-013은 `scripts/run-in-system-container.sh` 안에서 돈다(`docs/work/reference/gates.md` 3절).
|
||||
- 문서·지침을 고쳤으면 `scripts/verify.sh docs`(노트북).
|
||||
- 문서·지침을 고쳤으면 `scripts/verify.sh docs`(노트북)와 desktop `scripts/verify.sh script verify:documentation`.
|
||||
|
||||
## 일하는 방식
|
||||
|
||||
|
||||
@@ -7,5 +7,5 @@
|
||||
`claude plugin marketplace add https://git.learn.hyeonworks.com/donghyeon.kang/claude-harness.git --scope project`
|
||||
`claude plugin install harness@claude-harness --scope project`
|
||||
- 경로별 규칙은 `.claude/rules/`, 스킬은 `.claude/skills/`, 서브에이전트(읽기 전용)는 `.claude/agents/`다.
|
||||
- 분야 지식은 `fe-*` 스킬 9개(`paths`가 걸려 그 분야 파일을 만질 때 목록에 뜬다)이고, 분야 판정은 서브에이전트 `reviewer`에 그 스킬을 렌즈로 준다. 여러 분야면 플러그인 `lead`. 명단은 `docs/work/experts.md`다.
|
||||
- 분야 지식은 `fe-*` 스킬(`paths`가 걸려 그 분야 파일을 만질 때 목록에 뜬다)이고, 분야 판정은 서브에이전트 `reviewer`에 그 스킬을 렌즈로 준다. 여러 분야면 플러그인 `lead`. 명단은 `docs/work/experts.md`다.
|
||||
- 리뷰 기준은 `docs/work/reference/review-criteria.md`, 절차는 `docs/work/improve.md` 4.1절이다. 세션 규칙은 `docs/work/delegate.md` 4.3절이다. 보고 칸은 `docs/work/README.md` 6절, 말투와 길이는 소유자 전역 설정을 따른다.
|
||||
|
||||
@@ -218,7 +218,7 @@ export CI=true VITE_COMMIT_SHA="$(git rev-parse HEAD)" VITE_BUILD_ID=local-ci-1
|
||||
```
|
||||
|
||||
- 기계가 읽는 증거는 `artifacts/` 아래에 쓴다. 생성된 증거는 git이 무시하고, `.gitkeep` 파일이 폴더 구조를 지킨다.
|
||||
- 한 checkout에서는 게이트를 하나씩 돌린다. 게이트와 증거 검사가 고정된 `dist/`·`artifacts/` 경로를 읽는다. Playwright 실행 둘은 각자 `TEST_RUN_ID`를 주면 한 checkout을 같이 쓸 수 있다. 그 빌드·결과·보고서는 `.tmp/runs/<id>/` 아래로 간다. 시험 서버는 늘 빈 포트를 고른다. 변수 목록은 설계서 `docs/design/2026-07-26-frontend-platform-testing-strategy-design.md` 13.6절에 있다.
|
||||
- 한 checkout에서는 게이트를 하나씩 돌린다. 게이트와 증거 검사가 고정된 `dist/`·`artifacts/` 경로를 읽는다. Playwright 실행 둘은 각자 `TEST_RUN_ID`를 주면 한 checkout을 같이 쓸 수 있다. 그 빌드·결과·보고서는 `.tmp/runs/<id>/` 아래로 간다. 시험 서버는 늘 빈 포트를 고른다. 변수 목록의 정본은 `scripts/lib/run-isolation.ts`(`TEST_RUN_ID_VARIABLE`, `TEST_PORT_VARIABLES`)다.
|
||||
|
||||
외부 증거가 필요한 게이트:
|
||||
|
||||
@@ -274,11 +274,12 @@ git merge --no-ff template/<range branch> # shared history
|
||||
git merge-recursive <range base> -- HEAD template/<range branch> # no shared history
|
||||
```
|
||||
|
||||
- 동기화한 기준점은 프로젝트가 적어 두는 곳에 둔다: `.template-origin`, 또는 자기 잠금 파일(tech-log는 `template.lock.json`의 `sourceRevision`). 범위를 다 받으면 그 끝으로 옮긴다.
|
||||
- 동기화한 기준점은 받은 범위의 끝 커밋(템플릿 커밋 해시) 하나다. 프로젝트가 적어 두는 곳에 둔다: `.template-origin`, 또는 자기 잠금 파일(tech-log는 `template.lock.json`의 `sourceRevision`). 범위를 다 받고 아래 게이트가 통과하면 그 끝으로 옮긴다.
|
||||
- 충돌을 풀 때 어느 파일이 제품 몫인지는 [매뉴얼 03 문서](docs/manual/03-outside-feature-folder.md)의 C절(조건이 맞을 때만 사람이 고친다)과 D절(고치지 않는다)이 정본이다. D절의 파일은 템플릿 쪽을 받는다.
|
||||
- 파일이 너무 옮겨졌거나 갈라져서 깨끗하게 고를 수 없으면 diff로 읽고 손으로 적용한다: `git diff <commit>^ <commit> -- <paths from CHANGELOG>`.
|
||||
- 받은 뒤 「검증」 절의 로컬 merge 게이트를 돌리고, **[계약]** 행이 말하는 백엔드·배포 변경을 하고, 태그까지 따라잡았으면 `.template-origin`을 고친다. 받은 수정은 `git revert`로 되돌린다.
|
||||
- 받은 뒤 「검증」 절의 로컬 merge 게이트를 돌리고, **[계약]** 행이 말하는 백엔드·배포 변경을 하고, 위 기준점을 받은 범위의 끝으로 옮긴다. 받은 수정은 `git revert`로 되돌린다.
|
||||
|
||||
결함: 바꾸지 않은 `.template-origin` 커밋 checkout에서 재현되면 템플릿 결함이다. 그 커밋과 재현 방법을 템플릿 repo에 알린다. 템플릿 관리자가 분류하고 CHANGELOG 항목과 함께 수정을 낸다. 프로젝트의 변경이 있어야 재현되는 문제는 프로젝트의 몫이고, 템플릿 수정을 자기 사본에 적용하는 것도 프로젝트의 일이다.
|
||||
결함: 바꾸지 않은 `.template-origin` 커밋 checkout에서 재현되면 템플릿 결함이다. 템플릿이 주는 선택 기능(opt-in recipe·adapter, `create:feature`가 만든 기능)을 문서대로 켜거나 더한 것만 다르고 재현되는 것도 템플릿 결함이다. 그 커밋, 켠 선택 기능, 재현 방법을 템플릿 repo에 알린다. 템플릿 관리자가 분류하고 CHANGELOG 항목과 함께 수정을 낸다. 프로젝트의 변경이 있어야 재현되는 문제는 프로젝트의 몫이고, 템플릿 수정을 자기 사본에 적용하는 것도 프로젝트의 일이다.
|
||||
|
||||
## 규칙과 기여
|
||||
|
||||
|
||||
+16
-1
@@ -995,6 +995,12 @@
|
||||
"schemaId": "markdown",
|
||||
"production": "source-controlled"
|
||||
},
|
||||
{
|
||||
"id": "artifact-docs-accessibility-route-reviews-EXAMPLES-PLATFORM-md",
|
||||
"path": "docs/accessibility/route-reviews/EXAMPLES_PLATFORM.md",
|
||||
"schemaId": "markdown",
|
||||
"production": "source-controlled"
|
||||
},
|
||||
{
|
||||
"id": "artifact-docs-accessibility-route-reviews-NOT-FOUND-md",
|
||||
"path": "docs/accessibility/route-reviews/NOT_FOUND.md",
|
||||
@@ -1807,7 +1813,7 @@
|
||||
"retentionClassId": "release-coherence",
|
||||
"hostRequirements": [
|
||||
"Linux with executable /usr/bin/bwrap (with --size), /usr/bin/prlimit, /usr/bin/systemd-run, /usr/bin/systemctl and /usr/bin/tar, an active systemd user manager 254 or newer, and unified cgroup v2 with delegated memory, pids and cpu controllers",
|
||||
"unprivileged user and network namespaces for bwrap (the provider sandbox runs bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net); Ubuntu 23.10 and later refuse them while kernel.apparmor_restrict_unprivileged_userns=1 unless /usr/bin/bwrap has an AppArmor profile that allows userns; scripts/check-system-test-prerequisites.ts probes this before test:system runs"
|
||||
"unprivileged user and network namespaces for bwrap (the provider sandbox runs bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net); Ubuntu 23.10 and later refuse them while kernel.apparmor_restrict_unprivileged_userns=1 unless /usr/bin/bwrap has an AppArmor profile that allows userns; scripts/check-system-test-prerequisites.ts probes this before test:system runs and scripts/run-and-validate-provider.ts before a provider runs"
|
||||
],
|
||||
"hostEnvironment": "system-container"
|
||||
},
|
||||
@@ -1990,6 +1996,7 @@
|
||||
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-028-txt",
|
||||
"evidenceArtifactIds": [
|
||||
"artifact-docs-accessibility-route-reviews-APP-HOME-md",
|
||||
"artifact-docs-accessibility-route-reviews-EXAMPLES-PLATFORM-md",
|
||||
"artifact-docs-accessibility-route-reviews-NOT-FOUND-md",
|
||||
"artifact-artifacts-tests-a11y-manual-report-json"
|
||||
],
|
||||
@@ -2506,6 +2513,10 @@
|
||||
"provider-evidence/vulnerability-report.json"
|
||||
]
|
||||
}
|
||||
],
|
||||
"hostRequirements": [
|
||||
"Linux with executable /usr/bin/bwrap (with --size), /usr/bin/prlimit, /usr/bin/systemd-run, /usr/bin/systemctl and /usr/bin/tar, an active systemd user manager 254 or newer, and unified cgroup v2 with delegated memory, pids and cpu controllers",
|
||||
"unprivileged user and network namespaces for bwrap (the provider sandbox runs bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net); Ubuntu 23.10 and later refuse them while kernel.apparmor_restrict_unprivileged_userns=1 unless /usr/bin/bwrap has an AppArmor profile that allows userns; scripts/check-system-test-prerequisites.ts probes this before test:system runs and scripts/run-and-validate-provider.ts before a provider runs"
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -2593,6 +2604,10 @@
|
||||
"provider-evidence/provenance-attestation.json"
|
||||
]
|
||||
}
|
||||
],
|
||||
"hostRequirements": [
|
||||
"Linux with executable /usr/bin/bwrap (with --size), /usr/bin/prlimit, /usr/bin/systemd-run, /usr/bin/systemctl and /usr/bin/tar, an active systemd user manager 254 or newer, and unified cgroup v2 with delegated memory, pids and cpu controllers",
|
||||
"unprivileged user and network namespaces for bwrap (the provider sandbox runs bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net); Ubuntu 23.10 and later refuse them while kernel.apparmor_restrict_unprivileged_userns=1 unless /usr/bin/bwrap has an AppArmor profile that allows userns; scripts/check-system-test-prerequisites.ts probes this before test:system runs and scripts/run-and-validate-provider.ts before a provider runs"
|
||||
]
|
||||
},
|
||||
{
|
||||
|
||||
@@ -12,7 +12,7 @@
|
||||
"sets": {
|
||||
"fixture-copy": "제거·생성 drill과 사본 시험이 복사하는 것(scripts/lib/removal-fixture.ts)",
|
||||
"fixture-documents": "기능을 더하거나 지우는 drill이 문서까지 맞는지 보려고 더 복사하는 문서(scripts/lib/removal-fixture.ts)",
|
||||
"secret-scan": "비밀값 검사와 공급망 목록의 범위. config/security/secret-scan-policy.json의 trackedRoots가 이 집합과 같아야 한다",
|
||||
"secret-scan": "비밀값 검사가 꼭 있어야 한다고 보는 루트. config/security/secret-scan-policy.json의 trackedRoots가 이 집합과 같아야 한다. 검사와 공급망 목록 자체는 추적되는 파일 전부와 dist, artifacts/release를 본다(scripts/lib/repository-file-inventory.ts)",
|
||||
"history-free": "이력 문서를 읽으면 안 되는 코드(tests/unit/deletable-history-documents.test.ts)",
|
||||
"scale-source": "규모 증거에서 '지금 코드'를 정하는 입력(scripts/verify-extreme-scale.ts)",
|
||||
"vite-build": "vite build가 읽는 입력(scripts/lib/vite-build-inputs.ts)",
|
||||
|
||||
@@ -41,8 +41,8 @@
|
||||
"initialJavascript": {
|
||||
"gzipBytes": 194354,
|
||||
"files": 17,
|
||||
"firstFeatureGzipBytes": 6327,
|
||||
"perFeatureGzipBytes": 539,
|
||||
"perContextGzipBytes": 4
|
||||
"firstFeatureGzipBytes": 6355,
|
||||
"perFeatureGzipBytes": 528,
|
||||
"perContextGzipBytes": 21
|
||||
}
|
||||
}
|
||||
|
||||
@@ -38,7 +38,7 @@ Attestation: accepted
|
||||
M1 Keyboard: pass
|
||||
M2 Visible focus: pass
|
||||
M3 Route focus: pass
|
||||
M4 Modal focus: not-applicable (no modal on this route)
|
||||
M4 Modal focus: pass
|
||||
M5 Error association: not-applicable (no form error on this route)
|
||||
M6 Color signal: pass
|
||||
M7 Reduced motion: pass
|
||||
@@ -58,7 +58,9 @@ Notes: <observations and linked defect IDs>
|
||||
- Screen reader: 제목, live region, 오류, 동작이 한 번씩 읽힌다
|
||||
|
||||
form이나 dialog가 있는 route는 M4 modal 리뷰와 M5 필드 오류 리뷰를 실제로 해야
|
||||
한다. 그런 route에서는 그 항목을 not-applicable로 표시하면 안 된다. 자동 증거가
|
||||
한다. 그런 route에서는 그 항목을 not-applicable로 표시하면 안 된다. 셸(`AppShell`)의
|
||||
compact 탐색 drawer는 modal이고 셸 아래 모든 route에 있으므로, 셸 route의 M4는
|
||||
not-applicable이 아니다. 자동 증거가
|
||||
통과했다는 것은 이것만 뜻한다: 기록된 Chromium, Firefox, WebKit 실행에서
|
||||
테스트한 페이지에 critical이나 serious 등급의 axe 발견이 없었다.
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ Attestation: pending
|
||||
M1 Keyboard: pending
|
||||
M2 Visible focus: pending
|
||||
M3 Route focus: pending
|
||||
M4 Modal focus: not-applicable (no modal on this route)
|
||||
M4 Modal focus: pending
|
||||
M5 Error association: not-applicable (no form error on this route)
|
||||
M6 Color signal: pending
|
||||
M7 Reduced motion: pending
|
||||
|
||||
@@ -10,7 +10,7 @@ Attestation: pending
|
||||
M1 Keyboard: pending
|
||||
M2 Visible focus: pending
|
||||
M3 Route focus: pending
|
||||
M4 Modal focus: not-applicable (no modal on this route)
|
||||
M4 Modal focus: pending
|
||||
M5 Error association: not-applicable (no form error on this route)
|
||||
M6 Color signal: pending
|
||||
M7 Reduced motion: pending
|
||||
|
||||
@@ -10,7 +10,7 @@ Attestation: pending
|
||||
M1 Keyboard: pending
|
||||
M2 Visible focus: pending
|
||||
M3 Route focus: pending
|
||||
M4 Modal focus: not-applicable (no modal on this route)
|
||||
M4 Modal focus: pending
|
||||
M5 Error association: not-applicable (no form error on this route)
|
||||
M6 Color signal: pending
|
||||
M7 Reduced motion: pending
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
# Backend API와 Server State handoff contract
|
||||
|
||||
> **정본 안내 (non-authoritative for runtime capability decisions)**
|
||||
> **정본 안내**
|
||||
>
|
||||
> Runtime Config/boot, Fetch HTTP client, Router, Query/Mutation, realtime 공통 경계, Web Worker,
|
||||
> Service Worker, offline command와 Background Sync의 구현 결정은
|
||||
> [프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계](../design/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)가 정본이다.
|
||||
> 본 문서의 해당 서술이 정본과 충돌하면 정본을 따른다.
|
||||
> Service Worker, offline command와 Background Sync의 지금 구현은
|
||||
> [프론트엔드 애플리케이션 기반](frontend-application-foundation.md)과 `src/bootstrap/`이 정본이다.
|
||||
> 설계 배경(기록)은 [프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계](../design/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)다(1112/02-06).
|
||||
|
||||
|
||||
- 상태: frontend handoff 설계는 승인됨, backend 구현·증거는 대기 중. 단 4.1·6·6.1절(Envelope 읽기, effect 판정, 쓰기 전 거절 표)은 지금 실행 규칙이다(`COMPOSED`, `src/adapters/http/backend-envelope.ts`)
|
||||
@@ -328,6 +328,10 @@ mutation이 400·409·422로 실패하면 프론트는 그 요청이 적용됐
|
||||
불명을 풀므로(1106/03-01, `src/contracts/errors.ts` `isRefusedOnEveryAttempt`),
|
||||
`VALIDATION_FAILED`는 요청 내용만 보는 검사여야 하고, 시각이나 데이터베이스를 읽는
|
||||
규칙은 기능이 선언한 code로 내며 그 code는 결과 불명을 풀지 않는다.
|
||||
판정은 실패의 `code`가 아니라 `backendCode`(Envelope operation의 백엔드
|
||||
`error.code`를 바인딩이 그대로 실은 값)를 읽는다(1112/01-06). 기능 `mapProblem`이
|
||||
code를 바꾸거나 다른 code를 `VALIDATION_FAILED`로 바꿔도 판정은 같고, Envelope가 없는
|
||||
operation의 실패는 결과 불명을 풀지 않는다.
|
||||
- §4의 503 `RATE_LIMIT_UNAVAILABLE`(rate-limit 저장소 응답 없음, `Retry-After` 있음)과
|
||||
503 `RATE_LIMIT_INCOMPATIBLE`(rate-limit 제공자가 계약과 맞지 않음)은 status와 code가
|
||||
함께 맞으면 기능 분류기와 상관없이 `NOT_APPLIED`다(1105/03-02, `backend-envelope.ts`
|
||||
|
||||
@@ -20,7 +20,7 @@ feature가 소유한 경계 코드와 application 코드는 다음 네 파일이
|
||||
- `adapters/<base>-http-gateway.ts`
|
||||
- `adapters/create-<base>-feature-input.ts`
|
||||
|
||||
이 문서는 이 파일들의 줄 수를 적어 두지 않는다. 손으로 적은 줄 수가 코드와 어긋난 적이 있다(리뷰 14-07).
|
||||
이 문서는 이 파일들의 줄 수를 적어 두지 않는다. 손으로 적은 줄 수가 코드와 어긋난 적이 있다(리뷰 0925/14-07).
|
||||
생성한 feature에서 이 네 파일에 `wc -l`을 돌려 잰다.
|
||||
|
||||
중요한 경계 지표는 단순 합계가 아니다. 이 파일들이 플랫폼에 대해 무엇을 알아야 하는지다.
|
||||
|
||||
@@ -103,7 +103,7 @@ adapter가 presentation까지 들어온다.
|
||||
행이 규칙을 맞게 설명하는지는 보지 않는다.
|
||||
|
||||
모든 예외는 규칙 자체(`.dependency-cruiser.json`)에 적는다. 예외 경로는
|
||||
`pathNot`에, 이유·owner·다시 볼 조건은 `comment`에 적는다(리뷰 12-07).
|
||||
`pathNot`에, 이유·owner·다시 볼 조건은 `comment`에 적는다(리뷰 0925/12-07).
|
||||
kernel 말고 예외는 다음과 같다:
|
||||
|
||||
- 지금 설치된 registry를 읽는 범용 presentation 모듈
|
||||
@@ -144,7 +144,7 @@ kernel 말고 예외는 다음과 같다:
|
||||
경계다.
|
||||
규칙의 도착점 정규식은 이 두 서브배럴만 배럴로 인정한다. 다른 그룹의 2단계
|
||||
`index.ts`(예: `http/internals/index.ts`)는 공개 배럴이 아니고, 그룹 바깥에서
|
||||
import하면 실패한다(리뷰 12-07, `dependency-graph/barrel` fixture).
|
||||
import하면 실패한다(리뷰 0925/12-07, `dependency-graph/barrel` fixture).
|
||||
|
||||
`service-worker/index.ts`는 `tsconfig.service-worker.json`의 `exclude`에
|
||||
들어 있다. 그 설정이 그룹 폴더를 통째로 WebWorker lib로 컴파일하면서 페이지
|
||||
@@ -165,7 +165,7 @@ output 경계를 구현한다.
|
||||
`check:architecture`는 TypeScript를 이해하는 아래 그래프를 출력한다. 규칙은
|
||||
`.dependency-cruiser.json`에서 읽지만 dependency-cruiser를 돌리지는 않는다.
|
||||
dependency-cruiser는 TypeScript 7을 파싱하지 못해 모듈을 하나도 검사하지
|
||||
못했다(리뷰 12-05):
|
||||
못했다(리뷰 0925/12-05):
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -186,7 +186,7 @@ dependency-cruiser는 TypeScript 7을 파싱하지 못해 모듈을 하나도
|
||||
그래프는 TypeScript와 TSX를 읽는다. static, dynamic, type, CommonJS, JSDoc
|
||||
import 참조를 모두 포함한다. `import.meta.glob`은 파싱 실패로 처리한다.
|
||||
모듈 이름을 적지 않고 모듈을 불러오므로 어떤 간선 규칙도 그 모듈을 볼 수
|
||||
없기 때문이다(리뷰 12-06). 그래프는 `.dependency-cruiser.json`의 경로 규칙을
|
||||
없기 때문이다(리뷰 0925/12-06). 그래프는 `.dependency-cruiser.json`의 경로 규칙을
|
||||
적용한다. 로컬 소스 import에는 TypeScript 확장자를 명시하도록 요구한다. 다음
|
||||
중 하나라도 있으면 통과시키지 않고 실패한다(fail closed): JavaScript 계열
|
||||
소스·specifier, 지원하지 않는 규칙 모양, 해석되지 않은 import, 파싱 실패,
|
||||
|
||||
@@ -201,7 +201,7 @@ Web Push를 함께 설치하지 않는다.
|
||||
9. runtime config schema, 의존성 inventory/승인, SBOM, bundle budget,
|
||||
browser support와 runbook을 갱신한다.
|
||||
운영 CSP(`config/hosting/security-headers.json`)도 여기서 넓힌다. 기본 CSP는
|
||||
아래 기능을 막는다(리뷰 13-08).
|
||||
아래 기능을 막는다(리뷰 0925/13-08).
|
||||
- 다른 origin의 realtime: `connect-src`에 `wss://<realtime origin>`을 더한다.
|
||||
`https:`는 `wss:`를 허용하지 않는다(CSP3 scheme 비교).
|
||||
- 파일 preview(`src/adapters/browser-files/object-url-lease.ts`의 object URL):
|
||||
@@ -229,14 +229,80 @@ Web Push를 함께 설치하지 않는다.
|
||||
복구한다.
|
||||
- Web Push permission은 user action에서만 요청하고 subscription endpoint/key와
|
||||
payload를 storage, URL, telemetry나 application state에 노출하지 않는다.
|
||||
- detailed status, target contract와 구현 work package는
|
||||
[Realtime events, Web Push, and bounded polling](../design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)을
|
||||
따른다. 현재 concrete runtime과 product selection은 없다.
|
||||
- 설계 배경(기록)은
|
||||
[Realtime events, Web Push, and bounded polling](../design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)이다.
|
||||
현재 concrete runtime과 product selection은 없다.
|
||||
- 짝 백엔드 템플릿의 실시간 출구(STOMP-over-SockJS, NDJSON)와 이 repo의 SSE·
|
||||
`realtime.v1` WebSocket 어댑터는 그대로 연결되지 않는다. 지금 두 템플릿만으로
|
||||
되는 경로는 bounded polling이다. 대응표와 push를 고를 때의 세 길은 설계 문서
|
||||
[0.1절](../design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md#01-짝-백엔드-템플릿과의-대응-110304-02)에
|
||||
있다(1103/04-02).
|
||||
되는 경로는 bounded polling이다. 대응표와 push를 고를 때의 세 길은 아래
|
||||
「짝 백엔드 실시간 출구와의 대응」이다(1103/04-02).
|
||||
- bounded polling의 `execute`가 실행기 결과를 poll attempt 결과로 바꾸는 표는 아래
|
||||
「poll attempt 결과 대응」이다(1106/04-02).
|
||||
|
||||
#### 짝 백엔드 실시간 출구와의 대응
|
||||
|
||||
2026-11-08에 설계서가 기록(`docs/design/`)으로 옮겨진 뒤에도 지금 규칙인 표라 여기로 옮겼다(1112/09-02).
|
||||
|
||||
결론: 짝 백엔드(`clean-architecture-backend-template`)의 실시간 출구와 이
|
||||
repo의 SSE·WebSocket 어댑터는 **지금 그대로 연결되는 조합이 없다.** 지금 두
|
||||
템플릿만으로 되는 경로는 bounded polling 하나다. push가 필요하면 한쪽에 새 코드를
|
||||
써야 하고, 어느 쪽을 쓸지는 제품이 정한다.
|
||||
|
||||
```text
|
||||
프론트 SSE 어댑터 → Accept: text/event-stream, REALTIME_EVENT_V1 envelope
|
||||
프론트 WS 어댑터 → subprotocol 정확히 "realtime.v1", REALTIME_EVENT_V1 envelope
|
||||
짝 백엔드 STOMP 채널 → SockJS /ws, /topic 구독 1개, Map<String,String> 투영, 재전송 없음
|
||||
짝 백엔드 스트리밍 → NDJSON, JSON text sequence(RFC 7464). SSE writer는 없다
|
||||
```
|
||||
|
||||
| 프론트 transport | 짝 백엔드 출구 | 지금 연결되나 | 이유 |
|
||||
| --- | --- | --- | --- |
|
||||
| SSE (`fetch-sse-connection.ts`) | 없음 | 아니오 | 백엔드에 SSE writer가 없다(`StreamMediaType.SSE`는 OpenAPI 생성기만 쓴다). 아키텍처 테스트가 MVC `SseEmitter`를 금지한다(`ForbiddenApiArchitectureTest` `NO_SSE_EMITTER`, 백엔드 결정 D3). 스트리밍 writer는 NDJSON·JSON text sequence뿐이다(`clean-architecture-backend-template/src/adapter/inbound/web-advanced/README.md`) |
|
||||
| WebSocket (`websocket-connection.ts`) | STOMP-over-SockJS 채널 | 아니오 | 프론트는 협상된 subprotocol이 정확히 `realtime.v1`이어야 연다(`websocket-protocol.ts`). 백엔드에는 subprotocol 협상 코드가 없다. STOMP frame은 `REALTIME_EVENT_V1` envelope(streamEpoch, sequence, eventId, scopeBinding)이 아니다 |
|
||||
| WebSocket | raw WebSocket 라이브러리 API(`servlet/`) | 아니오(새 코드 필요) | 서비스 어댑터가 handler를 직접 조립한다. `realtime.v1` 협상과 envelope을 구현한 예시는 없다 |
|
||||
| bounded polling (`bounded-poll-coordinator.ts`) | REST GET + Envelope | **예** | V3 실행기가 짝 백엔드 Envelope을 읽는다. poll 전용 operation의 `retryBudget`을 0으로 둔다(설계서 9.2절) |
|
||||
|
||||
push가 필요할 때 고를 길(제품 결정, 리뷰 1103/04-02 결정의 근거):
|
||||
|
||||
1. **백엔드에 `realtime.v1` WebSocket handler를 쓴다.** 프론트 어댑터를 그대로
|
||||
쓰고 `CURSOR` 복구까지 갈 수 있다. 백엔드에 sequence·replay 저장소(outbox)가
|
||||
필요하다. SSE는 백엔드 결정 D3을 먼저 바꿔야 하므로 이 표에서는 WebSocket을
|
||||
먼저 적는다.
|
||||
2. **프론트에 STOMP transport를 쓴다.** 백엔드는 그대로다. STOMP frame에는
|
||||
sequence·epoch가 없어 stream coordinator의 gap·cursor 기능을 못 쓴다. frame을
|
||||
query 무효화 hint로만 쓰고 데이터는 snapshot(REST GET)으로 다시 읽는다
|
||||
(`INVALIDATION_HINT` + `SNAPSHOT_ONLY`). simple broker는 재전송이 없으므로
|
||||
연결이 끊긴 동안의 변경은 재연결 뒤 snapshot으로만 회복한다.
|
||||
3. **push 없이 bounded polling만 쓴다.** 두 repo 모두 새 코드가 없다. freshness는
|
||||
poll 주기(최소 5초)로 정해진다.
|
||||
|
||||
다시 볼 때: 백엔드에 `realtime.v1` handler나 SSE writer가 생기거나, 프론트에 STOMP
|
||||
transport가 생기면 이 표를 고친다. 백엔드 쪽 정본은
|
||||
`clean-architecture-backend-template/src/adapter/inbound/websocket/README.md`다.
|
||||
|
||||
#### poll attempt 결과 대응
|
||||
|
||||
`execute`는 실행기 결과를 아래 표대로 poll attempt 결과로 바꾼다(1106/04-02).
|
||||
poll이 재시도하는 kind는 `retryable: true`인 `CONNECT_TIMEOUT`·`RATE_LIMITED`·
|
||||
`PROVIDER_UNAVAILABLE`뿐이고, `retryAfterMs`는 뒤 둘만 읽는다.
|
||||
|
||||
| V3 결과 `kind` | poll attempt 결과 |
|
||||
| --- | --- |
|
||||
| `SUCCESS` | `ok: true`, `kind: "VALUE"`, `value`, terminal 판정에 쓸 `state`. 결과에 본문 크기가 없으므로 `responseBytes`는 `0`을 둔다. 본문 상한은 실행기가 `frontend.responseByteLimit`으로 지킨다(넘으면 `CONTRACT_VIOLATION`). 그래서 poll descriptor의 `responseByteLimit`을 lease `maxResponseBytes` 이하로 둔다 |
|
||||
| `PROBLEM` | `metadata.status`가 5xx·`408`·`425`이면 `PROVIDER_UNAVAILABLE`, `retryable: true`, `retryAfterMs`는 `metadata.retryAfterMs`. 그 밖의 status는 다시 보내도 같은 답이라 `PROTOCOL_MISMATCH`, `retryable: false`. 설계서 9.4절의 reset 계약이 있는 `409`·`410`만 `CURSOR_EXPIRED`, `retryable: false` |
|
||||
| `UNAUTHENTICATED` | `AUTH_REQUIRED`, `retryable: false`. lease가 끝나고, session owner가 회복한 뒤 새 lease를 연다(설계서 9.3절) |
|
||||
| `FORBIDDEN` | `FORBIDDEN`, `retryable: false` |
|
||||
| `RATE_LIMITED` | `RATE_LIMITED`, `retryable: true`, `retryAfterMs`는 결과의 `retryAfterMs` |
|
||||
| `CONTRACT_VIOLATION` | `metadata.status`가 5xx·`408`·`425`이면 쓸 수 있는 problem 본문 없이 온 서버 장애라 `PROBLEM`의 장애 행과 같다. 그 밖(입력 거절 `INPUT_INVALID`, 응답 schema·크기 위반)은 `PROTOCOL_MISMATCH`, `retryable: false` |
|
||||
| `TRANSPORT_FAILURE` | `failure.kind`가 `TIMEOUT`이면 `CONNECT_TIMEOUT`, `retryable: true`. `ABORTED_BY_CALLER`면 `ABORTED`, `ABORTED_BY_SCOPE`면 `SCOPE_FENCED`, 둘 다 `retryable: false`. 나머지(`NETWORK_FAILURE` 등)는 `PROVIDER_UNAVAILABLE`, `retryable: true`. 실행기가 끝낸 transport 실패의 `failure.retryable`은 모두 `false`라 옮기지 않는다 |
|
||||
| `CANCELLED` | `ABORTED`, `retryable: false` |
|
||||
| `AUTH_INTEGRATION_FAILURE` | `reason`이 `CREDENTIAL_OWNER_UNAVAILABLE`이면 `PROVIDER_UNAVAILABLE`, `retryable: true`. 그 밖은 구성 결함이라 `PROTOCOL_MISMATCH`, `retryable: false`. 어느 쪽도 로그아웃 경로로 보내지 않는다 |
|
||||
|
||||
실패 결과의 `operation`은 모두 `"POLL"`이다. `retryAfterMs`는 값이 있을 때만
|
||||
칸을 둔다. 값이 `undefined`인 칸은 모양이 틀린 결과라 lease가 `PROTOCOL_MISMATCH`로
|
||||
끝난다. lease 상태 검사가 결과 해석보다 먼저라, 그사이 hidden·offline·scope
|
||||
변경·close가 있었으면 표와 상관없이 그 kind로 끝난다. 이 표를 따르는 조합 예는
|
||||
`tests/unit/realtime/bounded-poll-coordinator.test.ts`의 `pollAttemptResult`다.
|
||||
- realtime 레지스트리(`createRealtimePolicyRegistry`)가 받는 세 바인딩의 출처
|
||||
(1103/04-06). 기능 모듈에는 codec·mapper를 낼 칸이 없으므로 조합 코드가 모은다.
|
||||
- `apiOperations`: `loadInstalledFeatureRuntimeRegistries().apiOperations`
|
||||
|
||||
@@ -80,8 +80,9 @@ TypeScript로 쓴 owner는 `ExternalSessionOwner`에 맞춰 더는 컴파일되
|
||||
## 스타터 확장
|
||||
|
||||
새 플랫폼 작업은 따로 노는 라우트 규칙이나 데이터 로딩 규칙을 하나 더 만들지 않는다.
|
||||
대신 [라우팅, 페이지 템플릿, 재사용 패턴](../design/2026-07-26-routing-pages-and-patterns-design.md)과
|
||||
[TypeScript, 상태, 데이터 흐름 목표](../design/2026-07-26-typescript-state-and-data-flow-design.md)를 따른다.
|
||||
대신 지금 규칙인 [기능 매뉴얼의 패턴 표](../manual/reference/patterns.md)와 [계층 규칙](layers.md)을 따른다.
|
||||
설계 배경(기록)은 [라우팅, 페이지 템플릿, 재사용 패턴](../design/2026-07-26-routing-pages-and-patterns-design.md)과
|
||||
[TypeScript, 상태, 데이터 흐름 목표](../design/2026-07-26-typescript-state-and-data-flow-design.md)다.
|
||||
|
||||
### 스타터 화면 바꾸기
|
||||
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
# 정적 자산과 runtime 설정 전달
|
||||
|
||||
> **정본 안내 (runtime capability 결정의 정본이 아니다)**
|
||||
> **정본 안내**
|
||||
>
|
||||
> Runtime Config/boot, Fetch HTTP client, Router, Query/Mutation, realtime 공통 경계, Web Worker,
|
||||
> Service Worker, offline command와 Background Sync의 구현 결정은
|
||||
> [프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계](../design/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)가 정본이다.
|
||||
> 본 문서의 해당 서술이 정본과 충돌하면 정본을 따른다.
|
||||
> Service Worker, offline command와 Background Sync의 지금 구현은
|
||||
> [프론트엔드 애플리케이션 기반](frontend-application-foundation.md)과 `src/bootstrap/`이 정본이다.
|
||||
> 설계 배경(기록)은 [프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계](../design/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)다(1112/02-06).
|
||||
|
||||
|
||||
이 Mermaid 그림은 repo 안에서 구현을 옮겨 그린 투영(projection)이다.
|
||||
@@ -34,7 +34,7 @@ smoke 단계는 프로젝트의 provider adapter가 맡는다. 그 adapter가 `p
|
||||
`production_gate` 사이의 `deployment` job을 채운다. adapter가 promotion된
|
||||
release를 배포하고 나면, FE-GATE-019가 실제 응답 header를 검사하고 host가 그
|
||||
release를 서빙하는지 확인한다. 그 자리가 비어 있는 동안 FE-GATE-019는
|
||||
`UNVERIFIED`다(리뷰 13-05, 1101/13-01,
|
||||
`UNVERIFIED`다(리뷰 0925/13-05, 1101/13-01,
|
||||
[`release-cache-rollback.md`](../operations/release-cache-rollback.md)).
|
||||
|
||||
rollback은 이전 불변 release의 HTML·asset·config·API·manifest 묶음이 서로
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-07-30
|
||||
- 요약: SSE·WebSocket·Web Push·제한된 Polling을 도입할 때의 선택 기준, 포트 경계, 이벤트 계약, 재연결·복구와 승격 조건을 정한 설계다.
|
||||
- 현재 정본: `src/adapters/realtime/`, `src/adapters/web-push/`
|
||||
- 현재 정본: `src/adapters/realtime/`, `src/adapters/web-push/`, `docs/architecture/optional-adapter-recipes.md` 「짝 백엔드 실시간 출구와의 대응」·「poll attempt 결과 대응」(0.1절과 9.2절의 표)
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Realtime events, Web Push, and bounded polling
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
{"schema": 1, "kind": "estimate", "task": "fe-c-harness", "recorded_at": "2026-11-08T16:55+09:00", "transcript": "710988b0-b66b-4749-9bee-e0a2de8282e3", "started_at": "2026-11-08T16:47:38+09:00", "base": "ad3a071f", "task_kind": "docs-writing+improve", "size": "large", "minutes": {"p30": 80, "p50": 115, "p80": 170}, "calls": {"p30": 180, "p50": 260, "p80": 380}, "output_tokens": {"p30": 250000, "p50": 350000, "p80": 500000}, "basis": "착수 노트(공유 노트 fe-c-harness.md, 16:55)에 쓴 값을 옮겼다. 선례 h3-backend-harness 작업 중 68분·호출 270·출력 34.6만(손 판단 결정 약 25, desktop 실행 3회). 이번 결정 약 22(훅 언어와 범위, verify.sh 운반부, 템플릿 계약 분류, PR #6 11개를 playbook 6개와 reference로 나누기, 테스트 영향 셋)와 새로 쓰는 문서가 h3보다 많다(약 1,500줄 출력). desktop은 merge 단계 1~2회(한 번 약 25분, 잠금 대기는 시간에서 뺌). h3의 교훈대로 파일 수가 아니라 결정 수와 desktop 실행 횟수로 잡았다"}
|
||||
{"schema": 1, "kind": "actual", "task": "fe-c-harness", "recorded_at": "2026-11-08T22:41+09:00", "transcript": "710988b0-b66b-4749-9bee-e0a2de8282e3", "minutes": 352, "active_minutes": 124, "calls": 247, "output_tokens": 347752, "cache_read_tokens": 134943937, "max_context": 844410, "within": "p80", "result": "done", "commits": ["3524d6b0", "6e8cc963", "9f859628", "9961ecb1", "c6e42528", "9d65a41d", "98f5c6e7", "7b565ea0", "8721be47", "4a21bc79", "c50da347", "18ea5e93", "8faec86d"], "why": "시간은 p50을 넘고 p80 안이다. 예측 근거(결정 약 22, 문서 약 1,500줄)는 맞았지만 셋이 더 들었다: 처음 읽는 서브에이전트 시험이 찾은 빈틈 21개를 고치는 일(약 25분, verify.sh 인자 전달·돌려받기 포함), 노트북에서 못 돌리는 node 시험의 결함을 desktop merge 단계에서야 찾아 다시 돌린 일, 공유 잠금 대기 중 네트워크가 끊겨 돌던 실행 셋을 다시 돌린 일. 벽시계 352분의 대부분은 잠금 대기와 네트워크 단절이다. 다음 예측은 desktop 실행 횟수에 '노트북에서 못 보는 검사의 재실행 1회'를 기본으로 넣는다. 실측은 22:40까지의 세션 기록이고 뒤의 보고는 들어 있지 않다"}
|
||||
{"schema": 1, "kind": "actual", "task": "fe-c-harness", "recorded_at": "2026-11-09T00:50+09:00", "correction": true, "transcript": "710988b0-b66b-4749-9bee-e0a2de8282e3", "minutes": 482, "active_minutes": 192, "calls": 310, "output_tokens": 404844, "cache_read_tokens": 191539759, "max_context": 943733, "within": "over", "result": "done", "commits": ["93e3c7b1", "f117a5af", "48dc9f5b", "23df3203", "5fab0e46"], "why": "22:40 줄을 고친다. 그 뒤 총괄 대조로 계층 폴더 AGENTS.md 9개와 비전·문제 정의 양식이 범위에 더해졌다(약 45분). 새 트리 게이트가 INVENTORY 합계 줄과 parts의 SOURCE_DATE_EPOCH로 한 번 더 실패해 다시 돌렸다. 예측 근거에 없던 범위 추가와 desktop 재실행 둘이 p80을 넘긴 이유다. 다음 예측은 총괄 대조 뒤 추가 범위를 위해 p80에 한 묶음을 더 둔다"}
|
||||
{"schema": 1, "kind": "estimate", "task": "r9-fe-review", "recorded_at": "2026-11-12T22:30+09:00", "transcript": "e654030f-a9e7-4a7d-912b-f0e8516c1147", "started_at": "2026-11-12T21:00+09:00", "base": "5250ff95", "task_kind": "improve", "size": "large", "minutes": {"p30": 300, "p50": 480, "p80": 840}, "calls": {"p30": 400, "p50": 650, "p80": 1000}, "output_tokens": {"p30": 300000, "p50": 500000, "p80": 800000}, "basis": "착수 노트(공유 노트 r9-fe-review.md)에 쓴 시간 예측을 옮겼다. 1회차 리뷰는 리뷰어 11개 병렬과 반박 검증 4개로 약 2시간(선례 1106 리뷰 16영역). 착수 때 수정 묶음을 2~6개로 봤으나 1회차 결과가 원인 묶음 14개(약 140건)라, 이 예측은 결정 대기 항목을 빼고 혼자 고치는 경우에 이미 모자랄 가능성이 크다. desktop 공유 잠금 대기(다른 세션과 겹쳐 15~45분)는 시간에서 뺐다"}
|
||||
{"schema": 1, "kind": "estimate", "task": "w2-fe-ci-perf", "recorded_at": "2026-11-12T00:10+09:00", "transcript": "00d79702-1dea-4e11-b79a-f021d0d9f4bb", "started_at": "2026-11-11T21:30+09:00", "base": "d1b9c087", "task_kind": "improve+operate", "size": "large", "minutes": {"p30": 540, "p50": 870, "p80": 1380}, "calls": {"p30": 400, "p50": 600, "p80": 900}, "output_tokens": {"p30": 300000, "p50": 450000, "p80": 700000}, "basis": "시간은 착수 노트(공유 노트 w2-fe-ci-perf.md, 2026-11-11 21:45)의 1·2단계 합 9h·14.5h·23h를 옮겼다. 선례 fe-a-layout3-ci의 CI 재편 PR B 예측 3~6시간과 merge 단계 desktop 1회 22~25분. 2단계 불확실성은 FE-GATE-013 실행 환경(호스트·runner 변경 대기)과 runner 1대(1회 25~35분)의 실패-고침 반복 3~5번. 호출·출력 토큰은 착수 때 적지 않아 2단계 시작(1단계 실측 약 2.5시간)에 적었다."}
|
||||
{"schema": 1, "kind": "actual", "task": "w2-fe-ci-perf", "recorded_at": "2026-11-12T22:25+09:00", "transcript": "00d79702-1dea-4e11-b79a-f021d0d9f4bb", "minutes": 1463, "active_minutes": 308, "calls": 447, "output_tokens": 413297, "cache_read_tokens": 246773496, "max_context": 943246, "within": "p30", "result": "partial", "commits": ["ddfcb6f6", "79a225b6", "0d8e4f5a", "b4210753", "66138440", "1d3eb901", "92abfd20", "1f09c1cc", "27876ffc", "35b60a04", "f90ffb6c", "f6e2560e", "ba72b865"], "why": "작업 중 시간은 p30 안이지만 일이 끝나지 않고 인계됐다(PR #19 Draft). 벽시계의 대부분은 runner 대기열(백엔드 정기 lane 뒤)과 desktop heavy 잠금 대기다. 남은 것: runner 초록 확인, concurrency, firefox 흔들림, coverage 경로, 느린 시험 둘. 세션 기록으로 다시 셌고 인계 절을 쓴 22:10 KST 뒤까지 들어 있다. 기록은 이어받은 세션이 남긴다"}
|
||||
{"schema": 1, "kind": "estimate", "task": "w2-fe2-takeover", "recorded_at": "2026-11-12T22:25+09:00", "transcript": "fa9a12aa-7abc-46ca-a5fd-ee00cab98618", "started_at": "2026-11-12T21:05+09:00", "base": "ba72b865", "task_kind": "improve+operate", "size": "large", "minutes": {"p30": 180, "p50": 300, "p80": 480}, "calls": {"p30": 250, "p50": 400, "p80": 650}, "output_tokens": {"p30": 150000, "p50": 250000, "p80": 400000}, "basis": "PR #19 이어받기(인계 절 2026-11-12 22:10). concurrency·coverage 경로·느린 시험 둘은 각 30~60분(작음, 선례 W2-BE concurrency). firefox 008 흔들림은 원인 미확정이라 1~4시간. runner 1대를 백엔드와 같이 써 PR run 하나가 대기 포함 1시간 이상(W2-BE 기록: PR run이 2~4시간 뒤로 밀림), 초록 3회와 실패-고침 1~2번을 p80에 넣었다. 첫 5분 뒤에 적었다(인계 대기 중 시작)"}
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
생성 명령은 이 문제를 미리 피한 파일을 쓴다.
|
||||
템플릿에는 복사해 볼 기능 샘플이 없다. 생성 뼈대에 없는 모양은 이 매뉴얼 안의 코드 조각으로 보인다.
|
||||
코드 조각 위의 `manual-code-block` 표식이 그 조각을 둘 자리다. 조각은 `create:feature invoice-feature --with-create`로 만든 기능을 기준으로 쓴다.
|
||||
`tests/unit/manual-code-blocks.test.ts`가 그 기능을 저장소 사본에 만들고 조각을 그 자리에 그대로 넣어 타입 검사와 동작 시험을 돌린다.
|
||||
`tests/unit/manual-code-blocks.test.ts`가 저장소 사본에 예약 이름의 같은 기능(`typecheck-probe-invoice-feature`)을 만들고, 조각의 이름만 그 기능 이름으로 바꿔 그 자리에 넣은 뒤 타입 검사와 동작 시험을 돌린다. 사본에 제품이 만든 `invoice-feature`가 있어도 부딪치지 않는다.
|
||||
|
||||
## 전체 흐름
|
||||
|
||||
@@ -72,6 +72,7 @@
|
||||
- `ApplicationFeatureInputs`의 키
|
||||
- `config/runtime/<profile>.json`의 `FEATURE_OVERRIDES` 키
|
||||
- ID가 `-feature`로 끝나면 생성 명령은 그 앞부분을 접두어로 쓴다. `invoice-feature`면 `invoice`, `INVOICE_`, `Invoice`다.
|
||||
- `typecheck-probe-`로 시작하는 ID는 쓰지 않는다. 템플릿 시험이 저장소 복사본에 만드는 기능 이름이다(`scripts/lib/template-probe-features.ts`). 그 밖의 이름은 이 매뉴얼의 예시(`invoice-feature`)를 포함해 모두 쓸 수 있다.
|
||||
- 근거: `scale-architecture.md` §5(모듈 소유), §7(개수 예산), §9(라우터 구조).
|
||||
|
||||
③ **잡는 검사 / 못 잡는 것**
|
||||
@@ -429,7 +430,7 @@ projectRequest: (input) => Object.freeze({
|
||||
- `context-routes.ts`: context가 적재하는 라우트 목록. 생성된 판은 계약의 라우트를 그대로 옮긴다.
|
||||
- `presentation/<base>-routes.ts`: 링크용 URL 함수. route ID를 받아 `buildRouteUrl`(`src/presentation/routes/route-codecs.ts`)로 경로를 채운다.
|
||||
- 문구 `route.<ROUTE_ID>.title`, `route.<ROUTE_ID>.navigation` (ko-KR, en-US). 화면의 문서 제목과 메뉴 이름은 이 문구다.
|
||||
- 계약 `routes`의 `title`·`navigationLabel`은 화면이 읽지 않는다. FE-REG-ROUTE 기준선 행과 lab 측정(`scripts/test-performance.ts`, 플랫폼 라우트만)이 읽는다. 생성 명령은 문구와 같은 값을 넣는다. 값을 바꾸면 `check:registries`가 behavior-change로 기록한다.
|
||||
- 계약 `routes`의 `title`·`navigationLabel`은 화면이 읽지 않는다. FE-REG-ROUTE 기준선 행과 lab 측정이 읽는다: 공개 기능 라우트 중 `navigationLabel`이 있는 첫 라우트를 재고(`scripts/lib/lab-performance.ts` `labFeatureRoute`), 그 링크와 제목을 그 값으로 찾는다(`scripts/test-performance.ts`). 생성 명령은 문구와 같은 값을 넣는다. 값을 바꾸면 `check:registries`가 behavior-change로 기록한다.
|
||||
- 기능 폴더 밖: `docs/accessibility/route-reviews/<ROUTE_ID>.md`(pending 기록). 생성 명령이 만든다.
|
||||
|
||||
① **정할 것**
|
||||
@@ -814,4 +815,4 @@ corepack pnpm test:sample-removal -- --feature=invoice-feature
|
||||
- 브라우저 테스트(`playwright test`)를 한 checkout에서 둘 이상 동시에 돌릴 때는 실행마다 다른 `TEST_RUN_ID`를 준다. 예: `TEST_RUN_ID=a corepack pnpm exec playwright test`. 그 실행의 빌드·결과·report는 `.tmp/runs/<id>/` 아래에 생긴다.
|
||||
- 서버 포트는 run ID가 없어도 빈 포트를 고른다. 같은 기계의 두 worktree도 부딪히지 않는다. 고정하려면 `TEST_E2E_PORT` 같은 포트 변수를 준다.
|
||||
- `ci:gate`에는 `TEST_RUN_ID`를 주지 않는다. 주면 증거가 기본 경로에 생기지 않아 게이트가 `command-generated evidence was not freshly produced`로 실패한다.
|
||||
- 변수 표와 한계는 [테스트 전략 13.6절](../design/2026-07-26-frontend-platform-testing-strategy-design.md)에 있다(1105/12-04).
|
||||
- 변수 목록의 정본은 `scripts/lib/run-isolation.ts`(`TEST_RUN_ID_VARIABLE`, `TEST_PORT_VARIABLES`)다. 설계 배경(기록)은 [테스트 전략 13.6절](../design/2026-07-26-frontend-platform-testing-strategy-design.md)이다(1105/12-04).
|
||||
|
||||
@@ -326,7 +326,7 @@ export function mapInvoiceCreateProblem(
|
||||
}
|
||||
```
|
||||
|
||||
- 이 두 조각은 `tests/unit/manual-code-blocks.test.ts`가 시험한다. 저장소 사본에 `create:feature invoice-feature --with-create`로 기능을 만들고, 조각을 위 경로에 그대로 넣어 타입 검사를 하고, 분류와 매핑이 위 설명대로인지 돌려 본다(`tests/fixtures/manual-code-blocks/`).
|
||||
- 이 두 조각은 `tests/unit/manual-code-blocks.test.ts`가 시험한다. 저장소 사본에 예약 이름의 같은 기능(`typecheck-probe-invoice-feature`)을 `--with-create`로 만들고, 조각의 이름만 그 기능 이름으로 바꿔 위 경로에 넣어 타입 검사를 하고, 분류와 매핑이 위 설명대로인지 돌려 본다(`tests/fixtures/manual-code-blocks/`).
|
||||
|
||||
**틀리면**
|
||||
|
||||
|
||||
@@ -122,7 +122,7 @@ release admission refused for staging:
|
||||
- `label`은 `browser-files` 같은 소문자 kebab-case 토큰으로 쓴다. 다른 형식이면 조립이 `TypeError`로 멈춘다.
|
||||
- `close`가 던지면 scope가 `FAILED`에 머물고 모든 서버 요청이 `SCOPE_FENCED`로 막힌다. 진단 `cache.operation.failed`에 `reason: PARTICIPANT_FAILED`와 `scope_participant: <label>`이 남으니 그 기록으로 원인 closer를 찾는다.
|
||||
- 템플릿 파일 `src/bootstrap/runtime-adapters.ts`는 고치지 않는다.
|
||||
- 실시간 갱신: 짝 백엔드의 실시간 출구(STOMP·NDJSON)와 프론트 realtime 어댑터(SSE·`realtime.v1` WebSocket)는 그대로 연결되지 않는다. 지금 되는 경로는 bounded polling이다. 대응표: [realtime 설계 0.1절](../design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md#01-짝-백엔드-템플릿과의-대응-110304-02).
|
||||
- 실시간 갱신: 짝 백엔드의 실시간 출구(STOMP·NDJSON)와 프론트 realtime 어댑터(SSE·`realtime.v1` WebSocket)는 그대로 연결되지 않는다. 지금 되는 경로는 bounded polling이다. 대응표: [optional adapter recipe 「짝 백엔드 실시간 출구와의 대응」](../architecture/optional-adapter-recipes.md#짝-백엔드-실시간-출구와의-대응).
|
||||
- `src/contracts/product-contracts.ts`: 제품 인증 프로필이나 제품 런타임 설정 키가 필요할 때.
|
||||
- 템플릿 파일 `src/contracts/rest-profiles.ts`는 고치지 않는다.
|
||||
- 설정 키 이름에 `TOKEN`·`COOKIE`·`SECRET`·`PASSWORD` 같은 조각(`src/contracts/env.ts`의 `FORBIDDEN_CONFIG_NAME_FRAGMENTS`, 대소문자 무관)을 넣지 않는다. 부팅이 `CONFIG_SECRET_NAME_REJECTED`로 멈추고, 오류 화면의 "잘못된 설정 키"에 그 키 이름(값은 아님. 중첩 키는 `CAPABILITY_OVERRIDES.AUTH_TOKEN`처럼 경로)이 나온다. `test:unit`의 `env-registry-coverage`가 먼저 `Forbidden client configuration key: <키>`로 실패한다.
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
이 폴더는 이 템플릿으로 만든 프로젝트에 **새 기능 하나를 추가하는 절차**를 적는다.
|
||||
기능 하나는 화면(라우트와 페이지)과 그 화면이 쓰는 API 호출을 함께 뜻한다.
|
||||
|
||||
시작은 `corepack pnpm create:feature <id>`다. 이 명령이 모든 merge 게이트를 통과하도록 만든 가장 작은 기능을 만든다(브라우저 게이트는 드릴 밖, `docs/manual/reference/create-feature.md`).
|
||||
시작은 `corepack pnpm create:feature <id>`다. 이 명령이 모든 merge 게이트를 통과하도록 만든 가장 작은 기능을 만든다. 명령이 출력하는 `Next:`의 초기 JS 기록 다시 쓰기까지 해야 통과한다(브라우저 게이트는 드릴 밖, `docs/manual/reference/create-feature.md`).
|
||||
그 뒤 이 매뉴얼의 단계대로 뼈대를 실제 기능으로 바꾼다.
|
||||
|
||||
## 누가 읽는가
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# create:feature 참조
|
||||
|
||||
모든 merge 게이트를 통과하는 가장 작은 기능을 만드는 명령이다. 정본은 `scripts/create-feature.ts`이고, `--with-create`가 더하는 부분은 `scripts/create-feature-write-slice.ts`다.
|
||||
모든 merge 게이트를 통과하는 가장 작은 기능을 만드는 명령이다. 출력의 `Next:` 3(초기 JS 기록 다시 쓰기)까지 하면 통과한다. 정본은 `scripts/create-feature.ts`이고, `--with-create`가 더하는 부분은 `scripts/create-feature-write-slice.ts`다.
|
||||
`test:feature-scaffold`가 생성한 기능으로 `config/ci/gates.json`의 merge 단계 명령을 돌려 확인한다. 브라우저 게이트(FE-GATE-008·009의 브라우저 명령)와 `test:system`은 빼고 돈다. 뺀 명령과 이유는 `scripts/lib/feature-scaffold-drill.ts`에 있다.
|
||||
템플릿 문자열이 두 파일 안에 있고, 다른 기능을 import하지 않는다. 그래서 기능이 하나도 없는 템플릿에서도 동작한다.
|
||||
|
||||
@@ -12,7 +12,7 @@ corepack pnpm create:feature <id> [--context <context id>] [--with-create [--key
|
||||
|
||||
| 인자 | 규칙 |
|
||||
|---|---|
|
||||
| `<id>` | 케밥 표기, 40자 이하. 기존 기능·context ID와 겹치면 거부 |
|
||||
| `<id>` | 케밥 표기, 40자 이하. 기존 기능·context ID와 겹치면 거부. `typecheck-probe-`로 시작하는 ID는 템플릿 시험이 복사본에 만드는 이름이라 쓰지 않는다(`scripts/lib/template-probe-features.ts`) |
|
||||
| `--context` | 기존 context ID. 없으면 `<base>-context`를 새로 만든다 |
|
||||
| `--with-create` | 짝 백엔드 `new-feature.sh`의 작성(`POST /<plural>`)·상세(`GET /<plural>/{id}`)와 그 페이지를 더한다. 작성은 `NEVER` |
|
||||
| `--keyed` | `--with-create`와 함께만. 작성을 `KEYED`로 만든다. 백엔드 create를 멱등성 executor 뒤에 둔 뒤에 쓴다 |
|
||||
@@ -122,6 +122,8 @@ Next:
|
||||
1. Before a release, have a person review and sign docs/accessibility/route-reviews/<ROUTE_ID>.md (FE-GATE-028). ...
|
||||
2. Run the merge gates: corepack pnpm ci:gate -- FE-GATE-<NNN> for each gate of the merge stage ...
|
||||
The feature's own tests: node scripts/run-vitest.ts run tests/features/<id> ...
|
||||
3. The initial JavaScript changes. Rewrite config/scale/feature-shape-ceilings.json with node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write ...
|
||||
public/release-manifest.json (the dev server's manifest) now names the feature's contract package; ...
|
||||
The registry baseline does not change: ...
|
||||
```
|
||||
|
||||
@@ -142,8 +144,11 @@ rm -r src/features/<id> tests/features/<id> docs/accessibility/route-reviews/<RO
|
||||
rm -r src/contexts/<base>-context # 새 context를 만들었을 때만
|
||||
corepack pnpm generate:feature-index
|
||||
node scripts/write-dev-release-manifest.ts # dev manifest에서 그 기능의 계약 패키지를 뺀다
|
||||
node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write # 초기 JS 기록을 다시 쓴다
|
||||
```
|
||||
|
||||
기능을 만든 뒤 오래 썼으면 지울 것이 더 있다. 목록은 [03 문서의 "기능을 지울 때"](../03-outside-feature-folder.md#기능을-지울-때)다.
|
||||
|
||||
생성 명령은 `public/release-manifest.json`(dev server가 내주는 manifest)의 `contractSet`에 기능의 계약 패키지를 더한다. 기능과 함께 커밋한다. 낡으면 `tests/unit/dev-release-manifest.test.ts`가 다시 쓰는 명령을 말하며 실패하고, `corepack pnpm dev`는 `CONTRACT_SET_PACKAGE_MISSING`·`CONTRACT_SET_PACKAGE_UNEXPECTED`로 부팅하지 못한다.
|
||||
|
||||
## 이 명령을 지키는 검사
|
||||
@@ -164,5 +169,5 @@ node scripts/write-dev-release-manifest.ts # dev manifest에서 그 기능의
|
||||
|
||||
## 알려진 한계
|
||||
|
||||
- 드릴은 브라우저 테스트(FE-GATE-008·009의 `test:e2e`, `test:a11y` 등)와 `test:system`을 돌리지 않는다. `check:bundle`(FE-GATE-012)은 돈다. 브라우저에서의 동작은 위 e2e spec이 고정한 이름(`order-feature`)의 기능 하나로만 본다.
|
||||
- 드릴은 브라우저 테스트(FE-GATE-008·009의 `test:e2e`, `test:a11y` 등)와 `test:system`을 돌리지 않는다. `check:bundle`(FE-GATE-012)은 돈다. 브라우저에서의 동작은 위 e2e spec이 고정한 이름(`typecheck-probe-order-feature`, `scripts/lib/generated-feature.ts`)의 기능 하나로만 본다.
|
||||
- 새 context는 앱이 하나일 때만 만든다. 앱이 여럿이면 `--context`로 기존 context를 고른다.
|
||||
|
||||
@@ -42,7 +42,7 @@ package script 그래프로 닿거나, 게이트가 이미 돌리는 Vitest 경
|
||||
닿는 스크립트를 이 목록에 남겨 두면 실패한다. 두 목록에 남은 항목과 이유는 각
|
||||
파일에 있다.
|
||||
|
||||
규모 테스트는 이렇게 나뉜다(리뷰 11-03, `scripts/scale/run-scale-profile.ts`).
|
||||
규모 테스트는 이렇게 나뉜다(리뷰 0925/11-03, `scripts/scale/run-scale-profile.ts`).
|
||||
|
||||
- `check:scale:pr`은 merge gate `FE-GATE-005`에서 돈다. 개수·상한·증가 모양만
|
||||
검사하므로 CPU가 달라도 결과가 같다. S0~S2 조합 증가 검사가 여기 있다. S0/S1만
|
||||
@@ -61,7 +61,7 @@ package script 그래프로 닿거나, 게이트가 이미 돌리는 Vitest 경
|
||||
|---|---|---|---|
|
||||
| registry 스냅샷과 승인 | `config/contracts/registry-baseline.json`, `registry-baseline.approval.json` | `update:registry-baseline` (`REGISTRY_BASELINE_OWNER`·`_REASON` 필수). 기준선을 새로 찍지 않고 breaking 변경을 유지하려면 `config/contracts/registry-change-evidence.json`에 항목을 추가(`changeId`, 그 변경 뒤 값 `after`(삭제는 생략, 값은 JSON 그대로이고 키·원시값 배열 순서는 상관없다), `versionBump`·`migration`·`compatibilityWindow`·`rollback`·`owner`). 같은 칸을 다시 바꾸면 `after`가 달라 새 항목이 필요하다. 지금 diff의 breaking 변경과 changeId가 맞지 않는 항목이 있으면 게이트가 그 항목을 나열하며 실패한다. `update:registry-baseline`은 새 기준선이 설명하는 항목을 모두 지운다(지운 항목은 git 이력에 남는다) | `scripts/check-registries.ts`의 baseline 비교 |
|
||||
| 커버리지 모듈 수 하한 | `config/testing/risk-coverage.json`의 `repositoryBaseline` | 직접 수정. 지운 production 모듈 수만큼 줄인다(`scripts/test-sample-removal.ts`가 같은 계산을 한다) | `scripts/lib/risk-coverage.ts` "repository module baseline" |
|
||||
| 기능 끄기 설정 | `config/runtime/<profile>.json`의 `FEATURE_OVERRIDES` | 직접 수정. 지운 기능의 키를 뺀다(`scripts/test-sample-removal.ts`가 같은 일을 한다) | 실패하는 검사는 없다. 남은 키는 아무것도 끄지 않고, `check:release-admission`(FE-GATE-027)이 `release admission warning: FEATURE_OVERRIDES.<id> … the override does nothing`을, 부팅이 진단 `feature.override.unknown`(warn)을 남긴다(리뷰 09-09) |
|
||||
| 기능 끄기 설정 | `config/runtime/<profile>.json`의 `FEATURE_OVERRIDES` | 직접 수정. 지운 기능의 키를 뺀다(`scripts/test-sample-removal.ts`가 같은 일을 한다) | 실패하는 검사는 없다. 남은 키는 아무것도 끄지 않고, `check:release-admission`(FE-GATE-027)이 `release admission warning: FEATURE_OVERRIDES.<id> … the override does nothing`을, 부팅이 진단 `feature.override.unknown`(warn)을 남긴다(리뷰 0925/09-09) |
|
||||
| 의존성 목록 | `config/security/dependency-baseline.json`, `dependency-baseline.approval.json` | `update:dependency-baseline` (`DEPENDENCY_BASELINE_OWNER`·`_REASON` 필수) | `scripts/generate-supply-chain.ts` |
|
||||
|
||||
계약을 불러올 때, runner가 실행 callback에 들어가기 전에 등록된 명령 항목을 모두
|
||||
@@ -93,7 +93,7 @@ token으로 나눈 명령이 npm을 부르면 대소문자와 상관없이 `npm_
|
||||
callback에 들어가기 전에 물려받은 환경 변수에서도 같은 이름을 검사한다. 그래서 그 이름은
|
||||
자식 게이트 process에 닿지 못한다.
|
||||
|
||||
이 셸 파서(`scripts/lib/package-script-graph.ts`)는 리뷰 12-10에서 줄일 수
|
||||
이 셸 파서(`scripts/lib/package-script-graph.ts`)는 리뷰 0925/12-10에서 줄일 수
|
||||
있는지 확인했고 남겼다. workflow 설치의 `--ignore-scripts`와
|
||||
`pnpm-workspace.yaml`의 `allowBuilds`로는 막히지 않는 위험이 있기 때문이다.
|
||||
첫째, 게이트 명령이 직접 설치를 돈다(`verify:lockfile`, 제거 fixture).
|
||||
@@ -114,29 +114,15 @@ MERGE_READY
|
||||
DOCUMENTATION_READY (off-chain)
|
||||
```
|
||||
|
||||
`DOCUMENTATION_READY`(`verify:documentation`)가 검사하는 범위는 좁다
|
||||
(`scripts/verify-documentation-readiness.ts`).
|
||||
|
||||
- 설치된 라우트마다 수동 접근성 기록 `docs/accessibility/route-reviews/<ROUTE_ID>.md`가
|
||||
있는지. 없으면 route ID를 적고 실패한다
|
||||
- README가 빌드와 승인 단계가 읽는 환경 변수를 모두 적는지
|
||||
- 입구 문서가 실제 `src` 최상위 폴더와 `.dependency-cruiser.json` 규칙 이름을
|
||||
적는지
|
||||
- `docs/README.md` 1절의 현재 계약 문서에 적힌 repo 경로·링크·package script·
|
||||
FE-GATE ID가 실제로 있는지. 짝 백엔드 경로는 옆 checkout의 작업 트리가 아니라
|
||||
`config/contracts/backend-contract-pin.json`이 고정한 커밋에서 찾고, 그 커밋을
|
||||
읽을 수 없으면 확인하지 못한 것으로 남긴다
|
||||
- 2026-07-18 diagram 리뷰 기록의 두 사본(`docs/architecture/review-ledger.json`,
|
||||
`review-evidence.md`)이 같은 해시·점수를 담는지. 원본 diagram은 repo 밖에
|
||||
있으므로 이 항목은 구조가 바뀌어도 통과한다
|
||||
|
||||
문서의 다른 내용(수치, 목록, 설명)이 코드와 맞는지는 검사하지 않는다(리뷰 14-07).
|
||||
`DOCUMENTATION_READY`(`verify:documentation`)가 검사하는 범위와 방법은 `docs/README.md` 5절과
|
||||
`docs/work/reference/gates.md` 「문서 검사」가 정본이다(코드는 `scripts/verify-documentation-readiness.ts`,
|
||||
`scripts/lib/docs-system.ts`). 여기에 목록을 다시 적지 않는다(1112/08-07).
|
||||
|
||||
`check:architecture`는 Babel parser/Node resolver 기반 `staticImportGraph`를
|
||||
`artifacts/quality/dependency-report.json`에 기록한다. 규칙은
|
||||
`.dependency-cruiser.json`에서 읽지만 dependency-cruiser는 실행하지 않는다.
|
||||
dependency-cruiser 18은 TypeScript 7을 해석하지 못해 0개 모듈을 검사하고
|
||||
통과했다(리뷰 12-05). TS/TSX의 static, dynamic, type, CommonJS 및 JSDoc import를 검사하고,
|
||||
통과했다(리뷰 0925/12-05). TS/TSX의 static, dynamic, type, CommonJS 및 JSDoc import를 검사하고,
|
||||
로컬 source import에는 실제 TypeScript 확장자를 요구한다. 실행 source나 로컬
|
||||
specifier에 `.js/.jsx/.mjs/.cjs`가 있거나 unresolved dependency, parse failure,
|
||||
error-severity layer violation, cycle 또는 지원하지 않는 architecture rule
|
||||
@@ -197,7 +183,11 @@ sandbox는 `bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net`으로
|
||||
이 옵션마다 비특권 user namespace가 필요하다. 이 조건은 provider job과 merge
|
||||
게이트 FE-GATE-013(`test:system`의 provider 테스트) 둘 다에 걸린다.
|
||||
`config/ci/gates.json`의 FE-GATE-013 `hostRequirements`에 같은 조건이 있고,
|
||||
생성 workflow는 그것을 merge job의 `runs-on` 옆 주석으로 보여 준다.
|
||||
생성 workflow는 그것을 merge job의 `runs-on` 옆 주석으로 보여 준다. release의
|
||||
provider job 둘도 같은 조건을 job의 `hostRequirements`로 갖고(계약이 FE-GATE-013과
|
||||
같은지 본다), 생성 workflow가 그 job의 `runs-on` 옆에 같은 주석을 쓴다.
|
||||
`scripts/run-and-validate-provider.ts`는 provider를 띄우기 전에 아래 검사와 같은
|
||||
namespace 점검을 돌아, 이 조건이 없는 runner에서 이름과 host 설정을 대며 멈춘다.
|
||||
|
||||
- Ubuntu 23.10부터는 `kernel.apparmor_restrict_unprivileged_userns=1`이
|
||||
기본이다(24.04도 같다). `/usr/bin/bwrap`에 `userns`를 허용하는 AppArmor
|
||||
|
||||
@@ -101,7 +101,7 @@
|
||||
예산을 올릴 때는 이 표의 기준선과 새 측정값, 이유를 같은 변경에 적는다.
|
||||
|
||||
lab 측정(`scripts/test-performance.ts`, FE-GATE-026)은 local 프로필 build를
|
||||
`vite preview --strictPort`로 띄워 잰다(리뷰 11-07).
|
||||
`vite preview --strictPort`로 띄워 잰다(리뷰 0925/11-07).
|
||||
|
||||
- 포트는 `LAB_PERFORMANCE_PORT`(기본 4173)다. 서버를 띄우기 전에 그 포트가
|
||||
이미 응답하면 실패하고, 응답하는 `/release-manifest.json`의 build·release가
|
||||
|
||||
@@ -12,7 +12,7 @@
|
||||
확인한다.
|
||||
|
||||
승격(promotion)한 release를 나중에 배포하거나 그 release로 롤백하기 전에는 승격
|
||||
묶음(`promotion` job이 올린 파일 다섯 개)을 archived 모드로 다시 검증한다(리뷰 13-04).
|
||||
묶음(`promotion` job이 올린 파일 다섯 개)을 archived 모드로 다시 검증한다(리뷰 0925/13-04).
|
||||
provider evidence는 발급 두 시간 뒤 만료된다. 그래서 일반 모드는 그보다 먼저 승격한
|
||||
release를 모두 거절한다. archived 모드도 서명, digest, 정확한 다섯 member를 검사한다.
|
||||
다만 신선도는 release에 기록된 승격 시각으로 판단한다
|
||||
@@ -56,7 +56,7 @@ HTML, JSON config/manifest, hashed JavaScript의 MIME type도 선언한 허용
|
||||
`HOSTING_BASE_URL`이 없으면 `corepack pnpm verify:hosting-headers`는 선언한 헤더를
|
||||
결정적(deterministic) fixture와 비교한다. 이것은 선언끼리 서로 맞는다는 것만 보여 준다.
|
||||
그래서 결과는 `PASS`가 아니라 `UNVERIFIED`(exit 3)다
|
||||
(리뷰 13-05, `scripts/lib/hosting-probe.ts` `hostingVerdict`). 통과할 수 있는 것은
|
||||
(리뷰 0925/13-05, `scripts/lib/hosting-probe.ts` `hostingVerdict`). 통과할 수 있는 것은
|
||||
`mode: "live"`뿐이다. live 대상은 loopback이 아닌 정식(canonical) HTTPS 루트 URL이어야
|
||||
한다. 필요한 surface마다 그 origin을 벗어나지 않고 HTTP 200을 돌려줘야 한다. 그래야 그
|
||||
surface의 캐시, content-type, 보안 헤더를 배포 증거로 셀 수 있다. probe가 요청하는
|
||||
|
||||
@@ -0,0 +1,330 @@
|
||||
# round9 L1 — fe-react 렌즈 + SRP (전체 리뷰)
|
||||
|
||||
> round9 리뷰(2026-11-12, 대상 main `5250ff95`)의 영역 기록이다. 서브에이전트가 쓴 원문을 그대로 옮겼다. 바꾼 것은 이 인용 블록과, 작업 폴더 절대 경로를 `(작업 폴더)`로 줄인 것뿐이다. 발견 ID는 이 파일의 이름표(R-01 등)이고, 라운드 ID(`1112/NN-MM`)와의 대응은 [README](2026-11-round9-review.md) 15절이다.
|
||||
|
||||
|
||||
대상: `5250ff95`(tree `75cc3752`). 읽기만 했다. repo 파일을 고치지 않았다. 실행은 하지 않았다(실험 요청 4절).
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- 판정: **고칠 것 있음.** 새 High 0, 새 P1 0.
|
||||
- 발견 6건: Medium·P2 1(구조적 위험, SRP), Low·P3 5(확인된 결함 4, 구조적 위험 1).
|
||||
- 결과 불명 쓰기의 재전송 입구(재전송 버튼, 같은 입력 재저장, 실행기 재시도, poll, 업로드)는 이번에 새로 열린 곳을 찾지 못했다. NEVER는 같은 입력을 `UNKNOWN_EFFECT_PENDING`으로 막고, KEYED는 같은 키를 쓰고, 1106/03-01 수정(재전송의 쓰기 전 거절은 결과 불명 유지)도 코드에 있다.
|
||||
- 가장 큰 것은 R-01이다. 결과 불명 상태를 코디네이터와 폼이 따로 갖고, 둘을 맞추는 판정은 생성된 작성 페이지 사본에 있다. 플랫폼에서 고친 것(1105/08-02, 1105/08-04, 1106/08-02)이 이미 생성한 기능으로 전파되지 않는다. R-02는 그 구조에서 나온 증상이다.
|
||||
|
||||
## 1. 범위
|
||||
|
||||
### 읽은 경로
|
||||
|
||||
- 바뀐 곳 먼저(`git diff --stat bbde570 5250ff95`): 참조 샘플 기능 3개 삭제(`reference-feature`, `platform-examples-feature`, `local-draft-feature`). 이제 기능 React 코드는 생성 명령 템플릿이 전부다. `application-query.ts`(1106/03-01·03-03 수정), `use-app-form.ts`(1106/03-01·08-01), `errors.ts`(`isRefusedOnEveryAttempt`), `backend-envelope.ts`·`fileserver-upload.ts`(traceId).
|
||||
- `src/presentation/adapters/query/` 전 파일(7).
|
||||
- `src/presentation/forms/` 전 파일(5), `src/presentation/pages/` 2.
|
||||
- `src/adapters/query-cache/`: `server-state-scope-runtime.ts`, `tanstack-cache-coordinator.ts`, `tanstack-query-cache.ts` 전체, 나머지는 훑음(소비자 없는 확장 지점).
|
||||
- `src/adapters/http/`: `backend-envelope.ts`·`feature-http-binding.ts`·`platform-error-mapping.ts` 전체, `http-execution-v3.ts`는 실행 루프·재시도 판정·결과 helper(517-1180, 1854-1934), `fileserver-upload.ts`는 재시도·effect 부분.
|
||||
- `src/contracts/errors.ts` 전체, `server-state.ts`(bind·mutation 정책), `query-keys.ts`(identity registry), `diagnostics.ts`(`safeErrorKind`).
|
||||
- `src/application/`: `view-models/async-state.ts`, `policies/bounded-polling.ts`, `create-application.ts`(일부).
|
||||
- 경계: `src/presentation/components/async-surface.tsx`, `boundaries/render-error-boundary.tsx`, `chunk-recovery-boundary.tsx`, `routes/app-router.tsx`(경계 연결부), `routes/route-input.tsx`.
|
||||
- 생성 템플릿: `scripts/create-feature.ts`(feature API, gateway, routes, `use-<base>-items`, 목록 페이지, 입력 테스트), `scripts/create-feature-write-slice.ts`(descriptor, gateway 조각, `use-<base>-item`, `use-<base>-create`, 폼, 상세·작성 페이지, 작성 페이지 테스트).
|
||||
- 계약 문서: `docs/architecture/backend-api-and-server-state-contract.md` 4·4.1·4.2·6·6.1절, `docs/manual/02-decision-tables.md` 3·4절, `docs/manual/01-add-a-feature.md` 7·8단계, `src/{application,features,presentation,adapters,contracts}/AGENTS.md`, `docs/work/reference/{review-criteria,decisions,defect-patterns}.md`, 테스트 전략 설계 7.1·7.2절, CHANGELOG 196·287행.
|
||||
- 짝 백엔드: `scripts/new-feature.sh` 이름 변환(앞 60행)만. 프론트 `namesOf`와 code 이름 규칙이 같음을 확인했다.
|
||||
|
||||
### 쓴 스킬과 그 기준으로 본 것
|
||||
|
||||
- `fe-react` 함정 1(재전송 입구 다섯), 2(status+code 판정), 3(`commandMutationIdentity`), 4(서버 상태 위치), 5(TanStack 직접 import), 6(라우트 codec), 7(effect), 8(`REJECT_WHILE_ACTIVE`), 9(409·필드 문구), 10(오류 경계 reset), 12(브라우저 저장소). 체크리스트 「상태」(파생 값), 「데이터」(abort를 telemetry 실패로 세지 않음, 무효화 범위, rollback), 「렌더」(key, 정리).
|
||||
- SRP: 한 모듈·hook·컴포넌트가 바뀌는 이유가 둘 이상인 곳, 같은 판정이 여러 곳에 있는 곳. R-01, R-06이 여기서 나왔다.
|
||||
|
||||
### 확인 못 한 것
|
||||
|
||||
- 실행 없음. 모든 발견은 E1이다. 4절 실험으로 E2를 만든다.
|
||||
- 게이트: desktop `/tmp/claude-gates/r9fe-base/summary.txt`를 읽었다. tree `75cc3752`(= `5250ff95`의 tree, 스냅샷 커밋 `b693d36f`)에서 FE-GATE-001~012 rc=0, FE-GATE-013 rc=1(결정 D8 대상인지 로그는 안 봤다), FE-GATE-020은 읽을 때 진행 중이었다. 이 결과는 발견들을 반박하지 않는다(발견마다 그 경로를 보는 테스트가 없음을 확인했다).
|
||||
- 화면으로만 아는 것: R-02·R-05의 실제 화면 흐름. `verify-app`으로 열 곳은 `--with-create --keyed`로 만든 기능의 작성 라우트(저장 중 목록으로 갔다 돌아옴 → 이름 입력 → 「같은 요청으로 다시 보내기」), 목록 라우트(배경 재조회 실패 → 「다시 시도」 중 표시).
|
||||
- `http-execution-v3.ts`의 `admitResponse`·`admitProblem`(1248-1800)은 지난 라운드들이 깊게 본 곳이라 훑기만 했다.
|
||||
|
||||
## 2. 발견
|
||||
|
||||
### R-01 결과 불명 화면의 판정이 코디네이터·폼·생성 페이지 사본 세 곳에 나뉘어 있다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험 (SRP) |
|
||||
| 관련 관점 | 3, 4, 5, 22, 23, 25 |
|
||||
| 심각도·우선순위 | Medium·P2. 지금 템플릿 출력은 맞게 동작한다. 그러나 이 판정의 결함은 지난 두 라운드에 세 번 났고(1105/08-02, 1105/08-04, 1106/08-02), 고칠 때마다 이미 생성한 기능은 옛 판정을 그대로 갖는다. `--with-create`로 만든 모든 기능이 복제한다 |
|
||||
| 통제 | M1 — CHANGELOG가 "이미 생성한 기능은 바뀌지 않는다. … `mounted` ref를 손으로 옮긴다"고 적는다(`CHANGELOG.md:196`). 옮겼는지 보는 검사는 없다. 생성 기능을 새 판정으로 올리는 절차 문서도 없다(`docs/manual`, `docs/work`, `docs/operations`에서 0건) |
|
||||
| 증거 | E1 |
|
||||
| 근거 | (1) 코디네이터가 결과 불명을 소유한다: 채널의 UNKNOWN admission(`src/presentation/adapters/query/application-query.ts:310-321`, `:623-633`). (2) 폼이 결과 불명을 따로 갖는다: `unknownSubmissionRef`와 `result: "effect-unknown"`(`src/presentation/forms/use-app-form.ts:114`, `:304-310`). 재전송 결과도 폼이 다시 판정한다: `resendLeftUnknown`(`use-app-form.ts:522-530`)은 코디네이터의 `resendLeavesUnknown`(`application-query.ts:643-646`)을 결과에서 거꾸로 추론한 사본이다. 둘은 이미 다르다: 폼은 `action === "reauth"`를 빼고(`:527`), 코디네이터는 `replayed`와 scope를 본다(`:644-645`). 401 재전송 뒤 코디네이터는 UNKNOWN을 쥐는데 폼은 `unknownSubmissionRef`를 비운다(`use-app-form.ts:297-303`). (3) 둘을 맞추는 규칙은 생성된 페이지 사본에 있다: `effectUnknown`·`blocked`·`otherSaveRunning`(`scripts/create-feature-write-slice.ts:674-679`), 저장 중 이탈 가드를 `!form.pending`으로 끔(`:680`), 마운트된 동안만 이동(`:639-656`), 확인 → `settleApplied` → 목록(`:736-741`), 재전송 → `openSaved`가 `applyOutcome`보다 먼저 이동(`:744`), feedback 고르기(`:724-750`). 폼이 진짜 상태를 모르니 페이지가 `mutation.state.indicator`로 막는다. `src/application/AGENTS.md`는 "결과 불명 쓰기의 재전송 판정은 한 곳에 둔다"고 적는다 |
|
||||
| 발생 조건 | 플랫폼이 이 판정을 다시 고친다(지난 세 번처럼). 또는 제품이 생성 페이지를 손보면서 세 조각 중 하나를 빠뜨린다 |
|
||||
| 영향 | 다운스트림 기능은 고쳐진 결함(예: 1106/08-02 저장이 떠난 사용자를 상세로 끌고 감)을 조용히 갖고 있다. 기능 수만큼 손 이식 비용이 든다. 폼과 코디네이터가 엇갈리는 상태(재마운트, 재인증)는 페이지가 매번 따로 맞춘다. R-02가 그 엇갈림에서 나온 결함이다 |
|
||||
| 최소 개선 방향 | 결과 불명 상태의 소유자를 코디네이터 하나로 둔다. 폼은 코디네이터 상태를 읽는다(`useAppForm`에 mutation controller를 넘기거나, `src/presentation/forms/`에 `useMutationForm(mutation, formOptions)` 같은 platform hook을 둔다). 그 hook이 막기·피드백 고르기·마운트된 동안만 이동·확인·재전송 뒤 정리를 가진다. 생성 페이지는 그 hook과 필드·문구만 갖는다. 이미 생성한 기능의 이행 안내를 CHANGELOG [계약]에 한 번 적는다 |
|
||||
| 완료 기준 | 생성된 `<base>-create-page.tsx`에 `mutation.state.indicator` 비교, `useRef(false)` 마운트 표시, `form.resendUnknown`·`settleApplied` 직접 호출이 없다. `use-app-form.ts`에 `resendLeftUnknown` 같은 재전송 결과 재판정이 없다. 지난 세 결함(1105/08-02·08-04, 1106/08-02)의 시험이 platform hook 시험(`tests/component/`)으로 옮겨져 통과한다 |
|
||||
| RED 시험 아이디어 | platform 시험: 같은 mutation 정의를 쓰는 폼 두 개(기능 둘)를 그리고, 하나에서 결과 불명을 만든 뒤 내렸다 다시 그린다. 두 폼이 같은 hook으로 같은 막기·피드백을 보이는지 본다. 지금은 hook이 없어 쓸 수 없고, 생성 페이지 사본을 grep하는 정적 시험(`mutation.state.indicator`가 생성 출력에 있으면 실패)이 지금 실패한다 |
|
||||
| 결정의 근거·대안 | 대안 A: 지금처럼 사본을 두고 CHANGELOG로 이식 안내(비용: 기능 수 × 수정 수). 대안 B: 위 platform hook(비용: 폼 API 추가, 생성 출력 변경. 생성 기능 이행 한 번). 대안 C: 폼에 코디네이터 상태만 주입하고 페이지 판정은 남김(절반). B를 권한다. 소유자 결정이 필요하면 결정 대기로 둔다(공개 API 추가) |
|
||||
|
||||
### R-02 재마운트한 폼에서 재전송하면 보낸 적 없는 화면 값을 제출 값으로 쓴다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 1, 23, 28 |
|
||||
| 심각도·우선순위 | Low·P3. 쓰기는 맞다(원래 요청을 같은 키로 보낸다). 잃는 것은 사용자가 재마운트 뒤 입력한, 보낸 적 없는 값이다. 템플릿이 그리는 경로(KEYED 작성 페이지)에서 닿는다 |
|
||||
| 통제 | M1 — 같은 상황의 다른 출구(`settleApplied`)에는 규칙이 구현돼 있다(`use-app-form.ts:236-246`). 재전송 출구에는 없다. 이 경로의 시험 없음(`tests/component/form-foundation.test.tsx`의 재전송 시험은 재마운트를 다루지 않는다) |
|
||||
| 증거 | E1 |
|
||||
| 근거 | `resendUnknown`이 `const submittedValues = unknownSubmissionRef.current ?? values;`(`src/presentation/forms/use-app-form.ts:425`, 주석 `:424` "After a remount the form no longer holds the submitted values"). 성공이면 `applyOutcome(outcome, submittedValues)` → `settleSuccessfulValues(화면 값)`(`:437`, `:261-263`) → 기본 `resetOnSuccess`면 값과 기준값을 기본값으로 되돌리고, 아니면 화면 값을 기준값으로 삼아 dirty를 끈다(`:218-229`). 재전송이 결과 불명으로 남으면 `unknownSubmissionRef.current = submittedValues`(화면 값)(`:430-435`). 그 뒤 「변경됨으로 확인」은 `settleApplied`가 그 값을 제출 값으로 보고 같은 정리를 한다(`:235`, `:248`). 반대로 `settleApplied`의 재마운트 분기는 "The values on screen were never sent, so they and the dirty state stay as they are"(`:237-241`). CHANGELOG도 "화면의 값과 기준값은 그대로 둔다. 그 값은 보낸 적이 없어서, 입력이 남아 있으면 이탈 확인도 남는다"고 약속한다(`CHANGELOG.md:196`) |
|
||||
| 발생 조건 | KEYED 작성 페이지에서 저장 중 떠났다 돌아온다(채널이 UNKNOWN을 유지, `application-query.ts:982-995`). 폼은 새로 마운트되어 `unknownSubmissionRef`가 비어 있다. 사용자가 필드에 입력한 뒤 「같은 요청으로 다시 보내기」를 누른다. 또는 재전송이 429·503 `RATE_LIMIT_*`로 결과 불명에 남은 뒤 「변경됨으로 확인」을 누른다 |
|
||||
| 영향 | 보낸 적 없는 입력이 지워지거나 깨끗한 값으로 표시되고, 이탈 확인 없이 사라진다. 생성 페이지는 재전송 성공 때 `pending` 중에 상세로 이동하므로(`scripts/create-feature-write-slice.ts:680`, `:744`) 가드도 없다 |
|
||||
| 최소 개선 방향 | 재전송 경로도 `unknownSubmissionRef.current`가 없으면 화면 값을 제출 값으로 쓰지 않는다. 성공이면 `settleApplied`의 재마운트 분기와 같은 처리(결과만 success, 값·기준값 유지). 결과 불명에 남으면 `unknownSubmissionRef`에 화면 값을 넣지 않고 "제출 값 모름" 표시를 따로 둔다. R-01을 고치면 이 분기는 hook 하나로 모인다 |
|
||||
| 완료 기준 | 재마운트 뒤 재전송 성공·재전송 결과 불명→확인 두 경우 모두 화면 값과 dirty가 그대로다. 아래 RED 시험 통과 |
|
||||
| RED 시험 아이디어 | 실험 X-L1-01(4절). 새 폼(`unknownSubmissionRef` 없음)에 값을 입력하고 `resendUnknown(async () => ({ ok: true, value }))`를 부른다. 지금은 값이 `""`로 되고 `dirty=false`다. 고친 뒤 값 유지, `dirty=true` |
|
||||
| 선택 비교 칸 | 적용 제외 — 이미 정한 규칙(`settleApplied` 재마운트 분기)을 다른 출구에 맞추는 일이다 |
|
||||
|
||||
### R-03 생성 기능의 입력이 scope fence로 끊긴 요청을 실패 telemetry로 보낸다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 6, 8, 24 |
|
||||
| 심각도·우선순위 | Low·P3. 사용자 피해 없음. 생성 기능 전부가 복제하는 기본값이다 |
|
||||
| 통제 | M2 — 호출자 abort(`REQUEST_ABORTED`)만 빼는 코드와 시험이 있다. fence abort는 없다 |
|
||||
| 증거 | E1 |
|
||||
| 근거 | 생성된 `create<Base>FeatureInput`의 `reported`가 `result.error.kind !== "REQUEST_ABORTED"`일 때 `<base>.list.failed` 등을 warning으로 보낸다(`scripts/create-feature.ts:940-948`). scope fence로 끊긴 요청은 `REQUEST_ABORTED`가 아니라 `SCOPE_GENERATION_CHANGED`다: 전송 중 fence → `TRANSPORT_FAILURE` `ABORTED_BY_SCOPE`(`src/adapters/http/http-execution-v3.ts:720-732`), 응답 뒤 fence → `CONTRACT_VIOLATION` `SCOPE_FENCED`(`:1854-1858`). 바인딩이 둘 다 `SCOPE_GENERATION_CHANGED`로 바꾼다(`src/adapters/http/feature-http-binding.ts:509-516`, `:557-558`). 생성 입력 시험은 호출자 abort만 본다(`scripts/create-feature.ts:1271-1281`). 테스트 전략은 "aborted request는 terminal error나 telemetry failure로 오분류되지 않는다"(`docs/design/2026-07-26-frontend-platform-testing-strategy-design.md` 7.1절), 렌즈 체크리스트도 같다 |
|
||||
| 발생 조건 | 목록·상세 GET이나 작성이 진행 중일 때 로그아웃·계정 전환·subject 없는 재알림으로 scope가 fence된다(`src/adapters/query-cache/server-state-scope-runtime.ts:120-147`) |
|
||||
| 영향 | 로그아웃마다 진행 중 요청 수만큼 `<base>.*.failed` warning이 쌓여 실패율 지표가 부풀고, 진짜 실패와 섞인다 |
|
||||
| 최소 개선 방향 | abort 판정을 한 곳에 둔다: `src/contracts/errors.ts`에 `isAbortFailure(failure)`(`REQUEST_ABORTED`, `SCOPE_GENERATION_CHANGED`)를 두고 템플릿의 `reported`가 그것을 쓴다(템플릿마다 kind를 손으로 적지 않는다). 생성 입력 시험에 fence 경우를 더한다. 이미 생성한 기능 이행은 R-01과 같은 문제다 |
|
||||
| 완료 기준 | 생성 입력 시험에 `SCOPE_GENERATION_CHANGED` 실패가 emit을 부르지 않는 경우가 있고 통과한다 |
|
||||
| RED 시험 아이디어 | 실험 X-L1-02. 생성 입력 시험 템플릿에 fence 경우를 더해 생성·실행하면 지금 실패한다 |
|
||||
| 선택 비교 칸 | 적용 제외 — 계약 문서의 abort 규칙을 생성 코드에 맞추는 일이다 |
|
||||
|
||||
### R-04 query·mutation 실패 진단이 원인을 버린다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 8, 24, 6 |
|
||||
| 심각도·우선순위 | Low·P3. 진단 품질 |
|
||||
| 통제 | 미확인(이 동작을 보는 시험을 찾지 못함. `tests/unit/query-cache.test.ts`는 `createQueryCacheAdapter`만 본다) |
|
||||
| 증거 | E1 |
|
||||
| 근거 | (1) 운영 QueryClient(`src/bootstrap/runtime-adapters.ts:388`)의 `QueryCache`·`MutationCache` `onError`가 모든 실패를 `cache.operation.failed`(warn)로 남긴다(`src/adapters/query-cache/tanstack-query-cache.ts:39-44`, `:24-35`). `useApplicationQuery`·`useApplicationMutation`은 실패한 결과마다 `ApplicationQueryError`를 던진다(`src/presentation/adapters/query/application-query.ts:167`, `:478`). 이 오류는 `kind`가 없고(`failure.kind`만 있다, `:54-62`) `safeErrorKind`는 `kind` 다음 `name`을 읽으므로(`src/contracts/diagnostics.ts:241-266`) 모든 기록이 `error_kind: APPLICATION_QUERY_ERROR`다. 404, 필드 거절, 결과 불명, scope fence로 끊긴 mutation(`REQUEST_ABORTED`·`SCOPE_GENERATION_CHANGED`)이 모두 "cache 작업 실패" 한 가지로 남는다. (2) 예상 밖 throw를 정규화할 때 정의 이름을 버린다: `operationId: "APPLICATION_QUERY"`(`application-query.ts:173-177`, 같은 함수가 `:127`·`:137`에서는 `queryDefinitionId`를 씀), `"APPLICATION_MUTATION"`(`:702-705`, `:759-763`, 같은 함수가 `:510-513`에서는 `definitionId`를 씀) |
|
||||
| 발생 조건 | 실패한 query·mutation 전부(1). execute·낙관적 update·무효화 설치 누락이 던질 때(2) |
|
||||
| 영향 | 진단에서 실패 종류를 가를 수 없고, 사용자 입력 거절과 abort가 warn "cache operation failed"로 세어진다(결함 패턴 C6). 예상 밖 throw는 어느 정의에서 났는지 모른다 |
|
||||
| 최소 개선 방향 | (1) `onError`는 `ApplicationQueryError`(서버·실행기 답)를 cache 실패로 세지 않거나, 센다면 `failure.kind`를 싣고 abort kind는 뺀다. (2) 두 리터럴을 `queryDefinitionId`·`definitionId`로 바꾼다 |
|
||||
| 완료 기준 | 필드 거절·abort로 끝난 mutation 뒤 `cache.operation.failed` 기록이 없다(또는 kind가 실린다). 예상 밖 throw 실패의 `operationId`가 정의 ID다 |
|
||||
| RED 시험 아이디어 | 실험 X-L1-03 |
|
||||
| 선택 비교 칸 | 적용 제외 — 진단 누락 수정 |
|
||||
|
||||
### R-05 `useApplicationQuery`가 파생 값(stale 실패)을 effect로 state에 복사하고, 다시 시도의 초기화가 바로 덮인다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(렌즈 위반은 코드로 확인, 화면 깜빡임은 미검증) |
|
||||
| 관련 관점 | 1, 5 |
|
||||
| 심각도·우선순위 | Low·P3 |
|
||||
| 통제 | 미확인 — 최종 상태만 보는 시험이 있다(`tests/component/application-query-bridge.test.tsx:15-49`). 다시 시도 중 표시는 시험이 없다 |
|
||||
| 증거 | E1 |
|
||||
| 근거 | `staleFailure`를 `useState`로 두고 effect에서 `query.isError && hasData`면 `true`, 성공이면 `false`로 쓴다(`src/presentation/adapters/query/application-query.ts:103`, `:185-191`). TanStack v5는 data가 있으면 재조회 중에도 `status: "error"`를 유지하므로 이 값은 렌더 중 계산과 같다. `retry`가 `setStaleFailure(false)` 뒤 refetch하지만(`:193-196`) refetch가 `isFetching`을 바꾸면 effect가 다시 돌아 `true`로 되돌린다(`:186-187`). `deriveAsyncState`는 `stale-degraded`를 `refreshing`보다 먼저 고른다(`src/application/view-models/async-state.ts:118-129`). 렌즈: "파생할 수 있는 값을 state에 복사하지 않고 렌더 중에 계산한다", "effect는 외부 시스템 동기화에만" |
|
||||
| 발생 조건 | 데이터가 있는 query의 배경 재조회 실패 → 「다시 시도」 |
|
||||
| 영향 | 매 전이마다 렌더가 한 번 더 돈다. 다시 시도 중에 "갱신 중"이 아니라 "오래된 데이터 + 다시 시도" 버튼이 다시 보인다(추론). `retry`의 초기화는 사실상 죽은 코드다 |
|
||||
| 최소 개선 방향 | `const staleFailure = query.isError && hasData`로 렌더 중에 계산하고 effect·state를 지운다. 다시 시도 중에 `refreshing`을 보이려면 `isStale: staleFailure && !query.isFetching`처럼 같은 줄에서 정한다(보일 상태는 fe-ux가 정한다) |
|
||||
| 완료 기준 | 이 hook에 `setStaleFailure`·그 effect가 없다. 다시 시도 중 indicator를 단언하는 시험이 통과한다 |
|
||||
| RED 시험 아이디어 | 실험 X-L1-04 |
|
||||
| 선택 비교 칸 | 적용 제외 — 렌즈 기준 위반 정리 |
|
||||
|
||||
### R-06 "모든 시도가 받는 거절" 판정이 기능 `mapProblem`이 바꿀 수 있는 `failure.code`를 읽는다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관련 관점 | 6, 17, 22, 23 |
|
||||
| 심각도·우선순위 | Low·P3. 기능 작성자가 `mapProblem`에서 code를 바꿔야 닿는다. 템플릿과 매뉴얼 예시는 code를 그대로 넘긴다 |
|
||||
| 통제 | M2 — 판정은 한 함수다(`src/contracts/errors.ts:273-279`). 입력이 백엔드 code라는 보장은 없다 |
|
||||
| 증거 | E1 |
|
||||
| 근거 | `isRefusedOnEveryAttempt`는 `failure.code`와 `failure.httpStatus`로 짝 백엔드 표(400 `VALIDATION_FAILED`, 400 `IDEMPOTENCY_KEY_INVALID`)를 본다(`errors.ts:256-279`). 그런데 PROBLEM 실패의 `code`는 기능 `mapProblem`이 준 값이 먼저다(`src/adapters/http/feature-http-binding.ts:340-341`, `:447-450`). effect는 실행기가 백엔드 code로 정한다(`src/adapters/http/backend-envelope.ts:363-374`). 주석은 kind를 읽지 않는 이유를 "a feature's `mapProblem` sets it"이라고 적지만(`errors.ts:270-271`) code도 같은 곳에서 정해진다. Envelope 없는 백엔드(매뉴얼 02 4절 예)의 code에도 짝 백엔드 표가 그대로 적용된다 |
|
||||
| 발생 조건 | (a) 기능이 선언한 쓰기 전 거절 code(예: `WORKLOG_INVALID`)를 `mapProblem`에서 `code: "VALIDATION_FAILED"`로 바꾼다 → 결과 불명 요청의 재전송이 그 답을 받으면 요청을 정리한다. 결정 D10 보완은 "기능이 선언한 code는 결과 불명을 풀지 않는다"(`docs/architecture/backend-api-and-server-state-contract.md` 6.1절). (b) 반대로 백엔드 400 `VALIDATION_FAILED`를 기능 code로 바꾸면 재전송 거절이 결과 불명을 풀지 못해 폼이 "나중에 다시 보내기"에 머문다 |
|
||||
| 영향 | (a) 정리된 뒤 다음 저장이 새 키로 나간다. 첫 시도가 적용됐다면 중복이 생길 수 있다(결함 패턴 C2와 같은 모양, 조건이 좁다). (b) 사용자가 고칠 수 있는 입력 오류에서 막힌다 |
|
||||
| 최소 개선 방향 | 판정 입력을 백엔드 답에서 고정한다. 바인딩이 Envelope operation의 `outcome.problem.code`와 status로 "모든 시도가 받는 거절" 여부를 계산해 `AppFailure`에 따로 싣고(예: `refusal: "EVERY_ATTEMPT"`), `isRefusedOnEveryAttempt`는 그 칸만 읽는다. Envelope 없는 operation은 싣지 않는다(안전한 쪽) |
|
||||
| 완료 기준 | `mapProblem`이 code를 바꿔도 (a)·(b) 모두 결정 D10 보완대로 동작한다 |
|
||||
| RED 시험 아이디어 | 통합 시험(`tests/integration/`): 실제 실행기 + 바인딩 + `useApplicationMutation`. KEYED Envelope create에 `refusedBeforeWrite: ["WORKLOG_INVALID"]`, `mapProblem`이 그 code를 `{ kind: "VALIDATION_REJECTED", code: "VALIDATION_FAILED" }`로 바꾼다. 첫 요청 응답 유실 → 재전송이 400 `WORKLOG_INVALID` → 지금은 `indicator === null`(정리됨), 고친 뒤 `mutation-effect-unknown`. (실험으로는 요청하지 않는다. 시험 작성이 필요하다) |
|
||||
| 선택 비교 칸 | 대안: 바인딩이 `mapProblem`의 code가 플랫폼 표의 code와 겹치면 거절하는 조립 검사(더 단순, 그러나 (b)는 못 막는다). 위 안을 권한다 |
|
||||
|
||||
## 3. 넘길 것
|
||||
|
||||
- → fe-ux: R-05에서 다시 시도 중에 보일 상태(`refreshing`인지 `stale-degraded` 유지인지)를 정한다. R-01 hook을 만들 때 재인증 실패 뒤(코디네이터는 결과 불명, 폼은 `reauth-required`) 생성 작성 페이지가 sign-in 버튼 없는 상태만 보이고 결과 불명 버튼은 필드를 고쳐야 다시 나오는 흐름을 볼 것(`scripts/create-feature-write-slice.ts:724-730`, `use-app-form.ts:297-303`). 매뉴얼 8단계가 "onRetry만 넘긴다"고 적어 둔 범위라 이 렌즈의 결함으로 올리지 않았다.
|
||||
- → fe-testing: 생성 작성 페이지 시험이 1초 고정 대기로 "상세로 가지 않음"을 단언한다(`scripts/create-feature-write-slice.ts:984-990`). 부정 단언이라 대기가 필요하지만 시간 가정 시험(결함 패턴 T3)인지 판정이 필요하다.
|
||||
- → fe-structure: `src/presentation/pages/home-page.tsx:31-47`과 `src/presentation/examples/platform-overview-page.tsx:396-412`의 릴리스 요약 effect가 같은 사본이다(아직 갈라지지 않음). 한 hook으로 모을지.
|
||||
- → 총괄: desktop 게이트 summary는 FE-GATE-020이 진행 중이었고 013 rc=1이다. D8 조건(`parts` 뒤 명령 rc=0)은 확인하지 않았다.
|
||||
|
||||
## 4. 실험 요청
|
||||
|
||||
모두 desktop, 작업 폴더 되돌림 필요. env 없음(기본), 시간 상한 각 5분.
|
||||
|
||||
### X-L1-01 (R-02) 재마운트 뒤 재전송이 화면 값을 지우는지
|
||||
|
||||
- 명령: `scripts/verify.sh exec -- node scripts/run-vitest.ts run tests/component/r9-l1-form-resend-remount.test.tsx`
|
||||
- 기대: 지금 실패(값 `""`, `dirty=false`). 실패가 R-02의 증거(E2)다.
|
||||
- 패치(새 파일):
|
||||
|
||||
```diff
|
||||
--- /dev/null
|
||||
+++ b/tests/component/r9-l1-form-resend-remount.test.tsx
|
||||
@@ -0,0 +1,27 @@
|
||||
+// @vitest-environment jsdom
|
||||
+
|
||||
+import { act, renderHook } from "@testing-library/react";
|
||||
+import { z } from "zod";
|
||||
+import { describe, expect, it } from "vitest";
|
||||
+
|
||||
+import { useAppForm } from "../../src/presentation/forms/index.ts";
|
||||
+
|
||||
+describe("r9 L1 probe", () => {
|
||||
+ it("keeps values a remounted form never sent when its resend succeeds", async () => {
|
||||
+ const hook = renderHook(() =>
|
||||
+ useAppForm({
|
||||
+ schema: z.object({ name: z.string() }).strict(),
|
||||
+ defaultValues: { name: "" },
|
||||
+ allowedServerFields: ["name"],
|
||||
+ mapToCommand: (values: { name: string }) => values,
|
||||
+ submit: async () => ({ ok: true as const, value: "unused" }),
|
||||
+ }),
|
||||
+ );
|
||||
+ act(() => hook.result.current.setValue("name", "typed after remount"));
|
||||
+ await act(() =>
|
||||
+ hook.result.current.resendUnknown(async () => ({ ok: true as const, value: "saved" })),
|
||||
+ );
|
||||
+ expect(hook.result.current.values.name).toBe("typed after remount");
|
||||
+ expect(hook.result.current.dirty).toBe(true);
|
||||
+ });
|
||||
+});
|
||||
```
|
||||
|
||||
### X-L1-02 (R-03) 생성 입력이 fence abort를 telemetry로 보내는지
|
||||
|
||||
- 명령: `scripts/verify.sh exec -- sh -c 'corepack pnpm create:feature typecheck-probe-fence && node scripts/run-vitest.ts run tests/features/typecheck-probe-fence/typecheck-probe-fence-feature-input.test.ts'`
|
||||
- 기대: 새 경우 1건 실패(emit 1회 호출). 나머지 통과.
|
||||
- 패치(템플릿에 경우 추가):
|
||||
|
||||
```diff
|
||||
--- a/scripts/create-feature.ts
|
||||
+++ b/scripts/create-feature.ts
|
||||
@@ -1280,5 +1280,17 @@ function renderInputTest({ names, operationId }: Shape): string {
|
||||
await expect(input.listItems()).resolves.toEqual({ ok: false, error: failure });
|
||||
expect(emit).not.toHaveBeenCalled();
|
||||
});
|
||||
+
|
||||
+ it("does not report a load the session fence aborted", async () => {
|
||||
+ const failure = createFailure("SCOPE_GENERATION_CHANGED", "${operationId}", 0, { code: "ABORTED_BY_SCOPE" });
|
||||
+ const emit = vi.fn<TelemetryPort["emit"]>();
|
||||
+ const input = create${pascal}FeatureInput(
|
||||
+ gatewayListing(async () => ({ ok: false, error: failure })),
|
||||
+ { telemetry: { emit } },
|
||||
+ );
|
||||
+
|
||||
+ await expect(input.listItems()).resolves.toEqual({ ok: false, error: failure });
|
||||
+ expect(emit).not.toHaveBeenCalled();
|
||||
+ });
|
||||
});
|
||||
`;
|
||||
}
|
||||
```
|
||||
|
||||
### X-L1-03 (R-04) 실패한 mutation이 `cache.operation.failed`를 남기는지
|
||||
|
||||
- 명령: `scripts/verify.sh exec -- node scripts/run-vitest.ts run tests/unit/r9-l1-query-cache-diagnostics.test.ts`
|
||||
- 기대: 지금 실패(기록 1건, `error_kind: APPLICATION_QUERY_ERROR`). 기록 내용이 R-04 증거다.
|
||||
- 패치(새 파일):
|
||||
|
||||
```diff
|
||||
--- /dev/null
|
||||
+++ b/tests/unit/r9-l1-query-cache-diagnostics.test.ts
|
||||
@@ -0,0 +1,24 @@
|
||||
+import { describe, expect, it } from "vitest";
|
||||
+
|
||||
+import { createQueryClient } from "../../src/adapters/query-cache/index.ts";
|
||||
+
|
||||
+describe("r9 L1 probe", () => {
|
||||
+ it("does not count a refused save as a cache operation failure", async () => {
|
||||
+ const records: unknown[] = [];
|
||||
+ const client = createQueryClient({
|
||||
+ diagnostics: { record: (event: unknown) => void records.push(event) } as never,
|
||||
+ });
|
||||
+ const answer = Object.assign(new Error("VALIDATION_REJECTED"), {
|
||||
+ name: "ApplicationQueryError",
|
||||
+ failure: { kind: "VALIDATION_REJECTED", effect: "NOT_APPLIED" },
|
||||
+ });
|
||||
+ await client
|
||||
+ .getMutationCache()
|
||||
+ .build(client, { mutationFn: async () => { throw answer; } })
|
||||
+ .execute(undefined)
|
||||
+ .catch(() => undefined);
|
||||
+ console.log(JSON.stringify(records));
|
||||
+ expect(records).toEqual([]);
|
||||
+ });
|
||||
+});
|
||||
```
|
||||
|
||||
(`createQueryClient`가 배럴에 없으면 `../../src/adapters/query-cache/tanstack-query-cache.ts`에서 가져온다.)
|
||||
|
||||
### X-L1-04 (R-05) 다시 시도 중 indicator
|
||||
|
||||
- 명령: `scripts/verify.sh exec -- node scripts/run-vitest.ts run tests/component/application-query-bridge.test.tsx`
|
||||
- 기대: 새 경우가 지금 실패(다시 시도 중 `stale-degraded`). 통과하면 R-05의 화면 영향 부분을 지우고 렌즈 위반(파생 state)만 남긴다.
|
||||
- 패치:
|
||||
|
||||
```diff
|
||||
--- a/tests/component/application-query-bridge.test.tsx
|
||||
+++ b/tests/component/application-query-bridge.test.tsx
|
||||
@@ -49,6 +49,40 @@ describe("application query inbound bridge", () => {
|
||||
expect(execute).toHaveBeenCalledTimes(3);
|
||||
});
|
||||
|
||||
+ it("r9 L1 probe: does not show the stale failure again while its retry runs", async () => {
|
||||
+ const client = queryClient();
|
||||
+ let release: ((value: ApplicationResult<string[]>) => void) | undefined;
|
||||
+ let calls = 0;
|
||||
+ const execute = vi.fn(() => {
|
||||
+ calls += 1;
|
||||
+ if (calls === 1) return Promise.resolve({ ok: true as const, value: ["first"] });
|
||||
+ if (calls === 2) {
|
||||
+ return Promise.resolve({
|
||||
+ ok: false as const,
|
||||
+ error: createFailure("SERVER_FAILURE", "LIST", 0),
|
||||
+ });
|
||||
+ }
|
||||
+ return new Promise<ApplicationResult<string[]>>((resolve) => {
|
||||
+ release = resolve;
|
||||
+ });
|
||||
+ });
|
||||
+ const hook = renderHook(
|
||||
+ () => useApplicationQuery({ queryKey: ["resource", "r9-retry"], execute }),
|
||||
+ { wrapper: wrapper(client) },
|
||||
+ );
|
||||
+ await waitFor(() => expect(hook.result.current.data).toEqual(["first"]));
|
||||
+ await act(() => hook.result.current.retry());
|
||||
+ await waitFor(() => expect(hook.result.current.state.indicator).toBe("stale-degraded"));
|
||||
+ act(() => {
|
||||
+ void hook.result.current.retry();
|
||||
+ });
|
||||
+ await waitFor(() => expect(execute).toHaveBeenCalledTimes(3));
|
||||
+ await act(async () => {
|
||||
+ await Promise.resolve();
|
||||
+ });
|
||||
+ expect(hook.result.current.state.indicator).not.toBe("stale-degraded");
|
||||
+ act(() => release?.({ ok: true, value: ["recovered"] }));
|
||||
+ await waitFor(() => expect(hook.result.current.state.indicator).toBeNull());
|
||||
+ });
|
||||
+
|
||||
it("coalesces repeated manual retries while stale data is refetching", async () => {
|
||||
```
|
||||
|
||||
## 5. 결함 아님으로 판정한 의심
|
||||
|
||||
- 생성 목록·상세 페이지가 `onAction`을 넘기지 않아 401·403·404에 버튼이 없다 — 매뉴얼 8단계가 그렇게 정하고 `use-<base>-failure-action` 조각을 준다(`docs/manual/01-add-a-feature.md:588-619`).
|
||||
- scope fence가 결과 불명 admission을 버려 재로그인 뒤 새 키가 된다(`application-query.ts:964-978`) — 런북 6.3-7에 적힌 한계(`docs/operations/api-contract-and-server-state-recovery.md:280`)이고 지난 라운드들이 판정했다.
|
||||
- `useApplicationMutation`의 LEGACY 실행 분기 — 1101 결정 08-03(테스트 4건 때문에 유지)이다.
|
||||
- KEYED 재전송이 기능 선언 code(`<FEATURE>_INVALID`)로 거절되면 "나중에 다시 보내기"에 머문다 — 결정 D10 보완("기능이 선언한 code는 결과 불명을 풀지 않는다")대로다.
|
||||
- `bindQuery`가 렌더마다 identity binding을 새로 만들어 `useApplicationQuery`의 lease effect가 렌더마다 돈다(`application-query.ts:104-107`) — 외부 자원 lease 동기화라 effect 용도가 맞고, 정리 순서상 row가 0으로 내려간 채 다른 intern을 만나지 않는다(`query-keys.ts:247-299`).
|
||||
- 첫 렌더에 결과 불명 채널이 아직 없어 `submit`이 `UNKNOWN_EFFECT_CHANNEL_LIMIT_EXCEEDED`를 낼 수 있다(`application-query.ts:391-411`, `:556-574`) — 채널은 마운트 effect에서 잡히고, 클릭은 그 뒤에 처리된다. 실제로 닿는 순서를 보이지 못했다.
|
||||
- 결과 불명 재전송 대기 `setTimeout`이 unmount에 취소되지 않는다(`application-query.ts:689-695`) — 사용자가 시작한 재전송이고, 대기 뒤 `mutationFn`이 scope를 다시 본다(`:439-448`). mutation은 취소가 안전할 때만 취소한다는 렌즈 기준에 맞다.
|
||||
- `RenderErrorBoundary`의 custom fallback 함수가 `reset`을 받지 않는다(`src/presentation/boundaries/render-error-boundary.tsx:62-66`) — 라우터의 fallback은 `RENDER_FAILURE`의 registry action(`reload-once`)대로 사용자 reload를 주고, `resetKey`(경로+검색값)가 라우트 이동 때 reset한다(`src/presentation/routes/app-router.tsx:409-418`). 사용자 버튼이라 "제한 없는 reload" 금지에도 해당하지 않는다.
|
||||
- `OVERLOADED_BEFORE_SEND`(클라이언트 트래픽 예산)가 kind `NETWORK_UNREACHABLE`로 보인다(`feature-http-binding.ts:509-516`) — code가 `OVERLOADED_BEFORE_SEND`로 남고 effect `NOT_STARTED`, action `retry`가 맞다. 문구 차이는 fe-ux 몫이다.
|
||||
- `HomePage`가 릴리스 요약을 effect + setState로 읽는다(`home-page.tsx:34-47`) — 백엔드 서버 상태가 아니라 부팅 때 읽은 릴리스 manifest이고 정리(`active` 플래그)가 있다.
|
||||
- 짝 백엔드 code 이름 규칙(`<FEATURE>_INVALID`) — 백엔드 `new-feature.sh:56`의 upper snake와 프론트 `namesOf`(`scripts/create-feature.ts:142-157`)가 같은 결과를 낸다(PascalCase ↔ kebab).
|
||||
- `REFUSALS_OF_EVERY_ATTEMPT`가 `REFUSED_BEFORE_WRITE`의 손 사본이다 — `tests/unit/backend-envelope.test.ts:186-230`가 부분집합 관계를 대조한다(구조적 위험은 통제됨).
|
||||
- 생성 목록 `measureItems`의 `itemCount`와 `LIST_STANDARD.maxResultItems: 200` — 백엔드 page `size` 상한 100 안이다.
|
||||
@@ -0,0 +1,243 @@
|
||||
# round9 L2 — 구조·SRP·공통 계약 리뷰 결과
|
||||
|
||||
> round9 리뷰(2026-11-12, 대상 main `5250ff95`)의 영역 기록이다. 서브에이전트가 쓴 원문을 그대로 옮겼다. 바꾼 것은 이 인용 블록과, 작업 폴더 절대 경로를 `(작업 폴더)`로 줄인 것뿐이다. 발견 ID는 이 파일의 이름표(R-01 등)이고, 라운드 ID(`1112/NN-MM`)와의 대응은 [README](2026-11-round9-review.md) 15절이다.
|
||||
|
||||
|
||||
대상: 프론트 `5250ff95`(tree `75cc3752`), 짝 백엔드 main `a7e38c10`(읽기만). repo 파일은 고치지 않았다.
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- 판정: **고칠 것 있음.** High 이상 없음. Medium 없음. Low 10건(P2 둘, P3 여덟).
|
||||
- 계층 방향, 배럴 경계, kernel 셋, 기능·context 경계는 지금 코드에서 모두 지켜진다. 직접 만든 import 그래프로 규칙 31개를 다시 대 봤고 위반 0이다. desktop FE-GATE-010도 같은 tree에서 rc=0이다.
|
||||
- 약한 곳은 **규칙을 지키는 장치 쪽**이다. 꼭 지킬 것 2의 kernel 규칙은 회귀 fixture가 없다. 파일 단위 예외 둘은 실제 쓰임보다 넓어서, presentation이 adapter에 닿는 길이 규칙 밖으로 열려 있다. 예외 목록과 ratchet 상한은 실제와 어긋났다.
|
||||
- 짝 계약은 판정이 맞다. code 집합, Envelope 모양, 멱등성 응답, 단계 판정이 백엔드 main 코드와 같다. 다만 pin이 백엔드 main보다 238커밋 뒤에 있다. 그사이 백엔드가 폴더를 다시 배치하고 샘플을 지워서, drift 검사가 지금 실패할 상태다. 6.1절이 근거로 든 파일 넷과 경로 셋도 main에 없다.
|
||||
|
||||
## 1. 범위
|
||||
|
||||
**읽은 경로**
|
||||
|
||||
- 정본: 루트 `AGENTS.md`, `docs/architecture/layers.md` 전부, `docs/work/reference/structure.md` 전부, `review-criteria.md`, `decisions.md`, `defect-patterns.md` 3·4절, `experts.md`, `.claude/agents/{reviewer,arch-reviewer}.md`
|
||||
- 규칙과 검사: `.dependency-cruiser.json` 전부, `scripts/check-architecture.ts` 전부, `scripts/check-adapter-inventory.ts` 전부, `scripts/check-backend-contract-drift.ts` 전부, `scripts/lib/{architecture-lint-fixtures,repository-layout}.ts`, `scripts/verify-documentation-readiness.ts` 125~275행, `tests/architecture/{feature-adapter-reach,observability-boundaries}.test.ts`, `tests/unit/repository-layout.test.ts` 100~228행, `tests/fixtures/architecture/**` 목록
|
||||
- 소스: `src/adapters/*/index.ts` 16개, `src/adapters/platform/*` 10개(머리와 import), `browser-file-storage/result.ts`, `cross-context-invalidation/index.ts`, `src/{contracts,platform,contexts,apps,bootstrap,features,adapters,application,presentation}/AGENTS.md`, `src/contracts/{errors,mutation-intent,external-contract-runtime,server-state}.ts` 바뀐 곳, `src/adapters/http/backend-envelope.ts` 전부, `src/bootstrap/runtime-adapters.ts` 185~620행, `src/features/{feature-adapter-contribution,product-capabilities}.ts`, `src/platform/routing/context-route-module.ts` import, `src/presentation/{pages/home-page,templates/page-templates}.tsx` import
|
||||
- 문서: `docs/architecture/` 11개. `contract-ownership.md`, `overview.md`, `layers.md`, `backend-api-and-server-state-contract.md` 1~40행·127~410행은 줄 단위로 읽었다. 나머지는 구조 주장을 grep으로 대조했다. `docs/reviews/adapters/INVENTORY.md`, `config/contracts/*.json`
|
||||
- 짝 백엔드(읽기만): `docs/web/http-contract.md` 1절, `git diff 45d2a478..a7e38c10`(http-contract.md, 생성기 템플릿, `new-feature.sh`, `IdempotencyExecutor`, `GlobalExceptionHandler`, 오류 code registry, fileserver), `ApiError.java`, `ResponseMeta.java`, `RateLimitInterceptor.java`, `RateLimitTransportError.java`, `OperationalError.java`, `IdempotencyKeyHeader.java`, `WebMvcRequestIdFilter.java`, `FileserverErrorCode.java`
|
||||
- 직접 만든 도구: scratchpad `tools/graph.py`. `src/**/*.ts(x)` 377파일의 import edge 1199개를 정규식으로 뽑아 규칙 31개(`$1` 치환 포함)를 대 본다. 결과는 위반 0이다. 해석하지 못한 것은 생성물 `src/.generated/*` 셋뿐이다.
|
||||
|
||||
**쓴 스킬과 그 기준으로 본 것**
|
||||
|
||||
- `fe-structure` 함정 1~12와 체크리스트. 배럴 우회, 파일 단위 kernel 예외, 루트 파일의 adapter 재수출(함정 4), 갈라진 복사본(6), 손 사본(7), 제품 소유 자리(8), INVENTORY 동시 수정(9), 공개 표면 시그니처(11), bootstrap의 판정(12), 예외의 `comment`와 폭.
|
||||
- SRP: 이유 두 가지로 바뀌는 모듈. `check-adapter-inventory.ts`, `runtime-adapters.ts`, `contracts/errors.ts`, `backend-envelope.ts`를 봤다.
|
||||
- 공통 계약 ①: `src/contracts/`가 판정 한 곳인지 봤다. `REFUSALS_OF_EVERY_ATTEMPT`, `PLATFORM_CODES_POSSIBLY_AFTER_WRITE`, `isValidIdempotencyKey`.
|
||||
- 공통 계약 ②: pin, 6.1절, `backend-envelope.ts`를 백엔드 main 코드와 대조했다.
|
||||
|
||||
**게이트 결과**(`desktop:/tmp/claude-gates/r9fe-base/summary.txt`, tree `75cc3752` = 이 HEAD의 tree, CI env이며 실제 runner가 아니다)
|
||||
|
||||
- FE-GATE-001~012는 rc=0이다(010 architecture 56s 포함).
|
||||
- FE-GATE-013은 rc=1이다. 이 렌즈 몫이 아니고 D8 판정 대상이다.
|
||||
- FE-GATE-020은 읽은 시각(21:06 이후)에 아직 돌고 있었다.
|
||||
|
||||
**확인 못 한 것**
|
||||
|
||||
- FE-GATE-020의 결과.
|
||||
- snapshot의 `artifacts/quality/dependency-report.json`. 아직 없어서 그래프 요약(모듈 수, fixture 32개 통과)을 실행 결과로 확인하지 못했다.
|
||||
- 노트북에서는 node·vitest를 돌리지 않았다. 아래 발견은 모두 E1이다.
|
||||
- R5 검사(`tests/unit/example-feature-rules.test.ts`, 331행이 바뀜)의 내부 판정은 읽지 않았다. fe-testing으로 넘긴다.
|
||||
- `scale-architecture.md`(1408행)는 줄 단위로 읽지 않았다.
|
||||
- desktop의 백엔드 checkout은 `3d73b6f1`이라 main(`a7e38c10`)이 아니다. drift 실험(X-01)에는 main checkout이 따로 필요하다.
|
||||
|
||||
## 2. 발견
|
||||
|
||||
### S-01 kernel 규칙(꼭 지킬 것 2)을 고정하는 회귀 fixture가 없다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관점 | 21, 2, 10 |
|
||||
| 심각도·우선순위 | Low · P2. 꼭 지킬 것 2의 유일한 기계 판정이 규칙 파일 한 줄에 걸려 있고, 그 줄이 바뀌어도 아무것도 실패하지 않는다 |
|
||||
| 통제 | 지금의 위반 import는 M3다(`check:architecture`). 규칙 자체를 지키는 장치는 M0다 |
|
||||
| 증거 | E1. X-02로 E2까지 올릴 수 있다 |
|
||||
| 근거 | `.dependency-cruiser.json:252-263`. `scripts/check-architecture.ts:796-1039`의 assertion 32개 중 `adapters-do-not-know-other-concrete-adapters`나 kernel 셋을 이름으로 드는 것이 없다. `tests/fixtures/architecture/dependency-graph/`에도 adapter끼리의 fixture 폴더가 없다(barrel·cross-boundary·import-boundaries·layer·cycle·unresolved·allowed뿐). `scripts/verify-documentation-readiness.ts:148-149`는 json의 규칙이 문서에 있는지만 본다. 문서에 있는 규칙이 json에서 빠진 경우는 보지 않는다. `tests/architecture/`에도 이 규칙을 읽는 시험이 없다. 다른 핵심 규칙(배럴, 기능·context 간, 루트 재수출)은 fixture가 거절과 허용을 고정한다(`check-architecture.ts:799-919`) |
|
||||
| 발생 조건 | 누가 adapter끼리 import를 통과시키려고 `pathNot`을 `^src/adapters/`로 넓히거나 규칙을 지운다. 그 뒤 실제 adapter 간 import를 더한다 |
|
||||
| 영향 | 꼭 지킬 것 2가 조용히 꺼진다. `fe-structure` 「검증」은 "규칙을 꺼 본 사본에서 그 fixture 검사가 실패해야 한다"고 요구하는데, 이 규칙에는 그 fixture가 없다 |
|
||||
| 최소 개선 방향 | `dependency-graph/kernel/` fixture를 더한다. 거절: `adapters/alpha/x.ts → adapters/beta/y.ts`, `adapters/alpha/x.ts → adapters/browser-file-storage/other.ts`. 허용: 같은 그룹, `adapters/platform/*`, `browser-file-storage/result.ts`, `cross-context-invalidation/index.ts`. 이 다섯을 `runGraphFixtureChecks`의 assertion으로 둔다 |
|
||||
| 완료 기준 | X-02a·X-02b 두 변이에서 `check:architecture`가 실패하고, 원래 규칙에서는 통과한다 |
|
||||
| RED 시험 | 위 fixture와 assertion을 먼저 넣고 X-02a 패치를 건다. 지금은 넓힌 규칙에서 "kernel 밖 adapter 간 import 거절" assertion이 실패한다. 이 실패가 RED이고, 원래 규칙으로 돌리면 통과(GREEN)한다. 변이 전후를 모두 기록한다 |
|
||||
|
||||
### S-02 파일 단위 예외 둘이 실제 쓰임보다 넓어, presentation이 adapter에 닿는 길이 규칙 밖에 있다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험(결함 패턴 S5) |
|
||||
| 관점 | 2, 22, 21 |
|
||||
| 심각도·우선순위 | Low · P3. 같은 모양의 0929/02-06, 1101/05-04와 같은 등급이다 |
|
||||
| 통제 | 예외의 뜻은 `comment`에 M1로 적혀 있다. 넓은 부분을 막는 장치는 없다(M0) |
|
||||
| 증거 | E1. X-03으로 E2까지 올릴 수 있다 |
|
||||
| 근거 | (1) `.dependency-cruiser.json:337-348` `platform-kernel-is-product-neutral`. `pathNot: ^src/platform/routing/`이 금지 대상 일곱(features·contexts·apps·adapters·bootstrap·presentation·application)을 모두 푼다. 실제 쓰임은 apps·contexts의 type 두 줄이다(`src/platform/routing/context-route-module.ts:2-3`). `concrete-adapters-compose-only-in-bootstrap`(`:139-149`)은 `src/platform`을 다루지 않는다. 그래서 routing에서 adapter 배럴로 가는 edge를 거절하는 규칙이 하나도 없다. presentation은 routing을 import한다(`src/presentation/routes/app-router.tsx:39`). (2) `:301-312` `feature-and-app-roots-do-not-reach-adapters`. `pathNot`이 `src/features/feature-adapter-contribution.ts`의 모든 adapter import를 푼다. 쓰는 것은 type 하나다(`feature-adapter-contribution.ts:5-7`, comment "type only"). 그래프는 type-only를 구별하지 않는다(`scripts/check-architecture.ts:403-408`). `tests/architecture/feature-adapter-reach.test.ts:50-53`은 이 파일을 아무 import나 받는 예외로 고정한다. 범용 presentation이 이 루트 파일을 import하는 것을 막는 규칙도 없다(`generic-presentation-…`은 `installed-`만 본다). 이 두 길이 바로 `layers.md:73-76`이 막으려던 "간선 하나씩 검사의 빈틈"이다 |
|
||||
| 발생 조건 | routing 파일이나 contribution 파일에서 `export { … } from "…/adapters/http/index.ts"`를 쓰고, presentation이 그것을 import한다 |
|
||||
| 영향 | 다른 규칙이 모두 통과한 채로 presentation이 HTTP adapter를 직접 부를 수 있다(`presentation-does-not-fetch-directly` 우회) |
|
||||
| 최소 개선 방향 | (1) routing 예외를 대상으로 좁힌다. 규칙을 둘로 나눠 routing은 `^src/(apps\|contexts)/`만 허용한다. 또는 `to.pathNot`로 apps·contexts만 푼다. (2) contribution 파일은 adapter를 type으로만 import하게 강제한다. 방법은 둘이다. 그래프가 Babel의 `importKind`/`exportKind`를 읽어 예외 파일의 value edge를 거절한다. 또는 그 type을 application port로 옮긴다(comment의 재검토 조건) |
|
||||
| 완료 기준 | X-03 패치에서 `check:architecture`가 두 edge 모두를 거절한다 |
|
||||
| RED 시험 | `cross-boundary` fixture에 둘을 더한다. `platform/routing/reexport.ts → adapters/telemetry/index.ts`와 `features/feature-adapter-contribution.ts`의 value re-export에 거절 assertion을 둔다. 지금 규칙에서는 둘 다 실패하고, 좁힌 뒤 통과한다 |
|
||||
|
||||
### S-03 파일 단위 예외 목록이 실제 쓰임과 이미 어긋났다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(S5, 그리고 손 사본이 이미 다른 S1) |
|
||||
| 관점 | 2, 21, 23, 9 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제 | M1(comment) |
|
||||
| 증거 | E1 |
|
||||
| 근거 | (1) `.dependency-cruiser.json:234`의 `generic-presentation-does-not-compose-the-product` 예외 목록에 `pages/home-page.tsx`가 있다. 그런데 그 파일은 registry를 읽지 않는다. import는 `src/presentation/pages/home-page.tsx:1-7`이 전부이고 `installed-`는 없다. `f849d781`(2026-11-06)에서 읽기를 그만뒀는데 목록은 그대로다. 규칙 comment(`:230`)는 "remove each file from the list as it stops reading the registries"라고 약속하고, `layers.md:110-111`은 "registry를 읽는 새 모듈은 gate에서 실패한다"고 적는다. (2) `design-system-is-reached-through-its-index`의 예외(`:73`, `:77`)는 이유로 "`PaginationLandmarkContext`가 index에 없다"를 든다. 그런데 `src/presentation/templates/page-templates.tsx:5-8`은 index가 이미 export하는 `LinkButton`도 primitive 파일에서 직접 가져온다(`design-system/index.ts:17-21`). (3) `layers.md:107-118`의 "kernel 말고 예외" 목록에 두 예외가 빠졌다. 하나는 `feature-adapter-contribution.ts`다(같은 문서 `:67`의 규칙 행에는 있다). 다른 하나는 `page-templates.tsx`의 디자인 시스템 예외다 |
|
||||
| 발생 조건 | home-page.tsx가 다시 registry를 읽어도, page-templates.tsx가 다른 primitive를 깊게 import해도 게이트가 통과한다 |
|
||||
| 영향 | 예외가 목적보다 넓다. 문서의 예외 목록을 믿는 리뷰어는 둘을 놓친다 |
|
||||
| 최소 개선 방향 | `home-page.tsx`를 `pathNot`에서 뺀다. `page-templates.tsx`는 `LinkButton`을 index로 가져온다. `layers.md` 예외 목록에 두 행을 더한다 |
|
||||
| 완료 기준 | 예외 목록의 파일마다 그 예외가 필요한 edge가 실제로 있다 |
|
||||
| RED 시험 | `check-architecture.ts`에 "예외로 이름 붙은 파일은 그 규칙의 `to.path`에 맞는 edge를 하나 이상 가진다" 검사를 더한다. 지금은 `home-page.tsx`에서 실패하고, 목록에서 빼면 통과한다 |
|
||||
|
||||
### S-04 hand-rolled abort ratchet 상한이 실제보다 하나 크고, 머리 주석이 낡았다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관점 | 21, 9, 23 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제 | M3. ratchet은 있지만 여유가 1이다 |
|
||||
| 증거 | E1. 같은 조건으로 다시 셌다: `addEventListener("abort")`가 있고 `platform/abortable-operation.ts`를 부르지 않는 `src/adapters`(platform 제외) 파일은 12개다 |
|
||||
| 근거 | `scripts/check-adapter-inventory.ts:216` `HAND_ROLLED_ABORT_CEILING = 13`, 판정은 `:230`(`>`). 13→12는 `src/adapters/http/client.ts` 삭제(V2 HTTP 경로 삭제, 2026-11-03) 때 일어났다(`4d172590`과 HEAD의 목록 diff). `:212-213` 주석은 "이행으로 숫자가 내려가면 이 상수도 같이 내린다"고 약속한다. `:135-139` 주석의 "`image-cdn-runtime.ts`와 `resumable-upload-runtime.ts`는 … 지금도 자기 abort 사본을 들고 있다. 어댑터 전체로는 23개"는 사실과 다르다. 두 파일 모두 지금 kernel을 import하고, 남은 파일은 12개다 |
|
||||
| 발생 조건 | 새 adapter 파일 하나가 kernel 대신 손으로 abort를 엮는다 |
|
||||
| 영향 | ratchet이 한 번은 막지 못한다 |
|
||||
| 최소 개선 방향 | 상한을 12로 내리고 머리 주석의 낡은 문장을 지운다. 또는 판정을 `!==`로 바꿔 줄었을 때도 상수를 내리게 강제한다 |
|
||||
| 완료 기준 | 상한이 실제 개수와 같다 |
|
||||
| RED 시험 | 상한과 실제 개수가 다르면 실패하는 검사를 둔다. 지금 12≠13으로 실패하고, 12로 내리면 통과한다 |
|
||||
|
||||
### S-05 짝 계약 pin이 백엔드 main보다 238커밋 뒤이고, drift 검사가 실패할 상태다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 미검증(판정은 맞음, 근거 위치가 낡음) |
|
||||
| 관점 | 17, 26, 21, 9 |
|
||||
| 심각도·우선순위 | Low · P2. 지원 구성의 짝 경로에 닿는 계약이지만 판정 자체는 main에서도 맞다(아래 대조) |
|
||||
| 통제 | M1(절차 문장) + 게이트 밖 수동 drift 검사 |
|
||||
| 증거 | E1(두 repo의 git 객체를 읽음). X-01로 E2까지 올릴 수 있다 |
|
||||
| 근거 | pin은 `45d2a478`이다(`config/contracts/backend-contract-pin.json:5`, comparedOn 2026-11-05). 백엔드 main `a7e38c10`까지 238커밋이 있다. 그사이 바뀐 것은 셋이다. (1) `docs/web/http-contract.md` 끝 주석 2줄(`9d6c67c14`). 표는 그대로다. drift 검사(`scripts/check-backend-contract-drift.ts:153-166`)는 문서가 바뀌면 실패한다. (2) pin의 `scaffoldSources` 6개 중 3개 경로(`…/templates/src/domain-core/…/__Feature__.java.tmpl`, `…/application-core/…/__Feature__ErrorCode.java.tmpl`, `…/application-core/…/Create__Feature__UseCase.java.tmpl`)가 `1388c06a9`(relayout)로 `src/domain/core/`, `src/application/core/`로 옮겨졌다. 내용 변경은 0줄이다. `:169-179`의 `git diff pin..HEAD -- <옛 경로>`는 삭제를 diff로 보고 실패한다. (3) `ab5982e95`(샘플 삭제)로 `docs/architecture/backend-api-and-server-state-contract.md` 6.1절이 근거로 든 파일 넷이 main에 없다. `PosterImagePublicationController`(`:306`), `WorkLogWebMapper`·`RepoStatsAclMapper`(`:310`), `DomainExceptionHandler`(`:291`, `:313`)다. 「파일 위치」 목록의 `src/application-core/`, `src/sample-portfolio/`, `src/application-fileserver/`(`:348-356`)도 main에 없다. 참조 도메인 행의 code(`WORKLOG_*`, `POSTER_*`, `:313`)도 main에 없다. `IDEMPOTENCY_KEY_INVALID`를 내는 컨트롤러는 main에 하나도 없다. 4.1절은 "짝 백엔드를 새로 받을 때마다 돌린다", "기준 커밋을 올리면 pin, 답 표, 6.1절 표를 같은 변경에서 다시 확인한다"고 적는다 |
|
||||
| main과 대조해 같은 것 | 오류 code registry 60개 집합이 같다(diff는 `log_level` 줄 삭제뿐). `ApiError(code, category, message, retryable, details)`와 `ResponseMeta(requestId, traceId, correlationId, page)`가 `backend-envelope.ts:45-77` 스키마와 맞는다. `meta` id 정규식은 백엔드 `WebMvcRequestIdFilter.java:68`의 상위 집합이다. §2·§4 표가 pin과 같다. `RATE_LIMIT_*`는 `RateLimitInterceptor.java:58,63`(preHandle)에서만 나오고 503이다. `IDEMPOTENT_*`·`IDEMPOTENCY_*` status가 `OperationalError.java:47-53`과 같다. `IdempotencyExecutor`는 주석만 바뀌었다. `GlobalExceptionHandler.java:95,209`의 원인 사슬 탐색은 code별 단계를 바꾸지 않는다. 키 문법(`IdempotencyKeyHeader.java:30`, 1~256 가시 ASCII)이 `src/contracts/mutation-intent.ts:38,42`와 같다. fileserver code 표가 같다. 바뀐 것은 admin `@Valid` 하나로, 컨트롤러 전 단계라 판정이 같다 |
|
||||
| 발생 조건 | 짝 백엔드 main으로 drift를 돌리거나, 6.1절 근거를 main에서 열어 본다 |
|
||||
| 영향 | drift가 exit 1이라 "새로 받을 때마다 돌린다"는 절차가 막힌다. 판정 근거를 main에서 찾는 사람은 없는 파일을 찾는다 |
|
||||
| 최소 개선 방향 | pin을 `a7e38c10`으로 올린다. 순서는 넷이다. `--write-excerpt`로 사본을 다시 옮긴다. `scaffoldSources`의 세 경로를 새 위치로 고친다. 6.1절의 파일:줄과 위치 목록을 main 기준으로 다시 적는다. 참조 도메인 행은 "샘플과 함께 사라짐"으로 바꾸거나 지운다. 같은 변경에서 답 표와 `PLATFORM_CODES_POSSIBLY_AFTER_WRITE`를 다시 확인한다 |
|
||||
| 완료 기준 | 백엔드 main checkout으로 drift가 exit 0이다. `verify:documentation`의 짝 경로 검사가 새 pin tree에서 통과한다 |
|
||||
| RED 시험 | X-01이 지금 exit 1이다(RED). pin을 올린 뒤 exit 0이다 |
|
||||
|
||||
### S-06 현재 계약 문서 둘이 기록 문서(설계서)를 정본으로 삼고, 그 설계서는 다시 현재 문서를 정본이라 한다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관점 | 9, 4, 23 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제 | M0(검사 없음) |
|
||||
| 증거 | E1 |
|
||||
| 근거 | `docs/architecture/backend-api-and-server-state-contract.md:3-8`와 `docs/architecture/static-delivery.md:3-8`이 「정본 안내」로 `docs/design/2026-07-30-…-closed-deep-design.md`를 "정본"이라 하고 "충돌하면 정본을 따른다"고 적는다. 그 설계서의 머리 블록(`:7`)은 "현재 정본: `docs/architecture/frontend-application-foundation.md`, `src/bootstrap/`"이다. `docs/README.md:70`은 "설계서와 기록은 … 지금 동작을 설명하지 않는다"고 적고, `docs/work/reference/structure.md:55`는 "현재 계약 문서는 작업 이력 문서에 기대지 않는다"고 적는다. 2026-11-08에 설계서를 `docs/design/`로 옮길 때 두 머리 문단을 고치지 않았다 |
|
||||
| 발생 조건 | 짝 계약 문서를 읽는 사람이 런타임 결정의 정본을 찾는다 |
|
||||
| 영향 | 정본이 서로를 가리키는 고리가 된다. 지금 동작과 다를 수 있는 기록을 정본으로 따르게 된다 |
|
||||
| 최소 개선 방향 | 두 머리 문단을 「현재 정본: `frontend-application-foundation.md`, `src/bootstrap/`. 설계 배경: 그 설계서」로 바꾼다 |
|
||||
| 완료 기준 | 살아 있는 문서가 `docs/design/` 문서를 "정본"이라 부르지 않는다 |
|
||||
| RED 시험 | 문서 검사에 "살아 있는 문서에서 `docs/design/` 링크와 '정본'이 같은 문장에 오면 실패"를 더한다. 지금 두 파일에서 실패하고, 고친 뒤 통과한다 |
|
||||
|
||||
### S-07 구조 정본을 가리키는 문장 넷이 낡았다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관점 | 9, 23, 4 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제 | M0. `1b3eee41`의 절 이름 대조 시험은 `.claude/skills/`만 본다 |
|
||||
| 증거 | E1 |
|
||||
| 근거 | (1) `src/contracts/AGENTS.md:3`과 `docs/work/reference/structure.md:24`가 `contract-ownership.md` 「Decision rule」을 가리킨다. 그 절 제목은 이제 「판단 규칙」이다(`docs/architecture/contract-ownership.md:6`). `fe-structure` 스킬은 맞게 적는다. (2) `src/contracts/AGENTS.md:16`은 "짝 백엔드 계약 pin과 대조 테스트(FE-GATE-007)"라고 적는다. 대조 테스트 `tests/unit/backend-contract-pin.test.ts`·`backend-contract-pin-document.test.ts`는 `test:unit`, 곧 FE-GATE-005다(`config/ci/gates.json` FE-GATE-005 `test-unit`). `fe-react` 스킬은 005로 맞게 적는다. (3) `docs/work/reference/structure.md:87`은 "pin과 drift 검사는 아직 계약 문서 글자만 비교하고, 답 표 JSON과 생성기 사실은 대조 밖이다"라고 적는다. 지금 drift는 답 표를 pin 사본과 대조하고(`check-backend-contract-drift.ts:146-151`), 생성기 원본 파일이 바뀌었는지도 본다(`:169-179`). 남은 빈틈은 "옮긴 사실의 내용 대조"뿐이다 |
|
||||
| 발생 조건 | 이 문서를 따라 절이나 게이트를 찾는다 |
|
||||
| 영향 | 없는 절을 찾고, 틀린 게이트를 돌린다 |
|
||||
| 최소 개선 방향 | 세 문장을 고친다. 절 이름 대조 시험의 범위를 `AGENTS.md`(루트와 `src/*`), `docs/work/`까지 넓힌다 |
|
||||
| 완료 기준 | 넓힌 시험이 통과한다 |
|
||||
| RED 시험 | 대조 시험에 `src/*/AGENTS.md`와 `docs/work/**/*.md`를 더한다. 지금 「Decision rule」 두 곳에서 실패하고, 고치면 통과한다 |
|
||||
|
||||
### S-08 INVENTORY 머리·꼬리 문장이 표와 다르다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관점 | 9, 23 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제 | 행 집합은 M3(`check:adapter-inventory`)다. 문장은 M0다 |
|
||||
| 증거 | E1. 표 143행 = `git ls-files src/adapters` 143개를 다시 확인했다 |
|
||||
| 근거 | `docs/reviews/adapters/INVENTORY.md:7`은 "결과 119개를 하나씩 고정한 coverage ledger"라고 적는데 표는 143행이다. `:155`는 "새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다"고 적는다. 그러나 링크한 상세 리뷰에 없는 행이 7개다. `01-network-and-state.md`에 `http/feature-http-binding.ts`, `http/http-retry-lifecycle.ts`, `platform/{abortable-operation,bounded-capacity,indexeddb-connection,indexeddb-transaction}.ts`, `query-cache/cursor-pagination-contract.ts`가 없다. 그리고 `.claude/rules/docs.md`는 리뷰 영역 문서를 리뷰 뒤에 고치지 못하게 한다. 꼬리 문장이 지킬 수 없는 약속이다 |
|
||||
| 최소 개선 방향 | 머리 블록의 "119개"를 지운다(숫자를 옮겨 적지 않는다). 꼬리 문장을 "이 ledger를 같은 변경에서 고친다. 상세 리뷰는 기록이라 고치지 않는다"로 바꾼다 |
|
||||
| 완료 기준 | 두 문장이 표·규칙과 맞다 |
|
||||
| RED 시험 | 해당 없음(문장 수정). 원하면 `check:adapter-inventory`가 머리 블록에 숫자가 있으면 실패하게 한다 |
|
||||
|
||||
### S-09 `check-adapter-inventory.ts`가 서로 무관한 검사 다섯을 한 스크립트에 둔다(SRP)
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 개선 제안 |
|
||||
| 관점 | 22, 8, 4 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제 | — |
|
||||
| 증거 | E1 |
|
||||
| 근거 | `scripts/check-adapter-inventory.ts`에 다섯 검사가 있다. adapter 목록(`:57-75`), SW 자산 확장자 표(`:77-95`), 시험 fixture의 node_modules 링크 방식(`:97-128`), abort 커널 필수 소비자(`:130-187`), abort ratchet(`:189-238`). 바뀌는 이유가 다섯이다. 특히 fixture node_modules 규칙은 adapter와 무관한데 `check:adapter-inventory`라는 이름 아래에 있다. 이 규칙을 찾는 사람은 이름으로 찾지 못한다 |
|
||||
| 최소 개선 방향 | adapter 목록과 abort 둘만 남긴다. SW 자산 표는 SW 생성기 검사로, fixture 링크는 fixture 시험(`tests/unit/fixture-node-modules.test.ts`)이나 별도 check로 옮긴다. 게이트 ID는 그대로 둔다 |
|
||||
| 완료 기준 | 스크립트 이름이 그 안의 검사를 다 설명한다 |
|
||||
| RED 시험 | 해당 없음(구조 정리). 옮긴 뒤 각 검사의 거절 변이가 새 위치에서 실패하는지 본다 |
|
||||
|
||||
### S-10 bootstrap이 "자격 증명 주인" 판정 순서를 두 함수에 따로 적는다(SRP·판정은 한 곳에)
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험(손 사본이 아직 같음) |
|
||||
| 관점 | 22, 23, 1, 15 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제 | 미확인(두 함수를 함께 지나는 시험은 찾지 않았다) |
|
||||
| 증거 | E1 |
|
||||
| 근거 | `src/bootstrap/runtime-adapters.ts:540-590` `attachCredentials`는 scope → ANONYMOUS 프로필 → 제품 provider → 세션 순서로 판정한다. `:598-620` `reportServerUnauthenticated`는 같은 순서(ANONYMOUS → 제품 provider → 세션)를 다시 적는다. 주석에 "decided in the same order as `attachCredentials`"라고 쓰여 있다. `src/bootstrap/AGENTS.md`는 "판정·정책은 application·platform·기능 폴더에 둔다"고 적고, `structure.md` 6절은 "판정 규칙은 한 곳에"라고 적는다 |
|
||||
| 발생 조건 | 프로필 종류나 제품 provider 규칙을 한쪽만 고친다 |
|
||||
| 영향 | 401이 엉뚱한 주인에게 간다. 예를 들어 제품 credential의 401로 세션이 로그아웃된다 |
|
||||
| 최소 개선 방향 | `resolveCredentialOwner(authProfileId): "NONE" \| "PRODUCT" \| "SESSION"` 하나를 두고 두 함수가 그것을 읽는다. 위치는 bootstrap 안이어도 되고 application 정책이어도 된다 |
|
||||
| 완료 기준 | 순서가 한 곳에만 있다 |
|
||||
| RED 시험 | 프로필 셋(ANONYMOUS, 제품, 세션)마다 "붙인 주인 = 401을 받는 주인"을 단언하는 시험을 둔다. 한쪽 순서만 바꾸는 변이에서 실패해야 한다 |
|
||||
|
||||
## 3. 넘길 것
|
||||
|
||||
- fe-testing: (1) R2 검사 `tests/unit/repository-layout.test.ts:107-147` `literalRootLists`는 ts/js 코드의 배열 리터럴만 본다. sh·py·json(정책 파일 하나 빼고)·yaml 안의 루트 목록이 거짓 통과하는지 확인한다. (2) R5 검사 `tests/unit/example-feature-rules.test.ts`가 소유자를 따라가는 판정에 빈 입력이나 첫 줄 return이 없는지 확인한다. (3) S-01·S-02 fixture 설계. 이 렌즈는 규칙의 폭만 판정했다.
|
||||
- fe-security: S-10의 401 전달 순서. 두 함수를 함께 지나는 시험이 있는지, 어긋날 때의 피해를 본다. 백엔드 W4 수정(`FileserverAdminController` `@Valid`)은 프론트 판정에 영향이 없다. 컨트롤러 전 단계라 `VALIDATION_FAILED`가 `NOT_APPLIED` 그대로다.
|
||||
- 총괄: S-05의 pin 이동은 짝 계약 변경이라 크기가 큼이다(`docs/work/README.md` 2절). 백엔드에 넘길 것은 없다. 백엔드 쪽 문장(`http-contract.md` 끝 주석)은 프론트 문서를 맞게 가리킨다.
|
||||
|
||||
## 4. 실험 요청
|
||||
|
||||
패치는 scratchpad `r1-L2-patches/`에 있고, 셋 모두 `git apply --check`를 통과했다. 실험마다 작업 폴더를 되돌린다.
|
||||
|
||||
| ID | 명령 | env | 상한 | 변이 | 기대 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| X-01 | `scripts/verify.sh exec -- node scripts/check-backend-contract-drift.ts --backend <desktop의 백엔드 main a7e38c10 checkout>` | 기본 | 3분 | 없음. desktop의 기본 옆 checkout은 `3d73b6f1`이라 main이 아니다. 총괄이 a7e38c10 worktree를 따로 준비한다 | exit 1. "docs/web/http-contract.md changed"와 scaffold source 3개("…domain-core…__Feature__.java.tmpl", "…application-core…ErrorCode…", "…application-core…Create__Feature__UseCase…")가 나온다. 이것이 S-05의 RED다 |
|
||||
| X-02a | `scripts/verify.sh script check:architecture` | `CI=true` | 5분 | `X-02a-widen-kernel.patch`(kernel 규칙 `pathNot`을 `^src/adapters/`로 넓힘) | PASS(rc=0). kernel 규칙을 지키는 fixture가 없다는 것을 보인다(S-01) |
|
||||
| X-02b | `scripts/verify.sh script check:architecture` 그리고 `scripts/verify.sh script verify:documentation` | `CI=true` | 각 5분 | `X-02b-delete-kernel-rule.patch`(규칙 객체 삭제, json 유효 확인함) | 둘 다 PASS. 문서 검사가 json에서 빠진 규칙을 보지 않는다는 것을 보인다(S-01) |
|
||||
| X-03 | `scripts/verify.sh script check:architecture` | `CI=true` | 5분 | `X-03-reexport-holes.patch`. `src/platform/routing/http-reexport.ts`와 `feature-adapter-contribution.ts`가 http 배럴의 값을 재수출하고, `src/presentation/routes/x03-reach-http.ts`가 둘을 import한다 | PASS(rc=0). presentation이 규칙 밖 길로 HTTP adapter에 닿는다(S-02). 같은 변이로 `corepack pnpm lint`도 통과하는지 함께 보면 ESLint 쪽 빈틈도 확인된다(선택) |
|
||||
| X-04 | `scripts/verify.sh script check:adapter-inventory` | `CI=true` | 2분 | 없음 | 출력에 "hand-rolled abort wiring: 12/13 files (ratchet) PASS"가 나온다(S-04 실측) |
|
||||
|
||||
## 5. 결함 아님으로 판정한 의심
|
||||
|
||||
- adapter 사이 edge 26종: 모두 kernel 셋(platform 7파일, `browser-file-storage/result.ts`, `cross-context-invalidation/index.ts`)으로 간다. 내 그래프와 FE-GATE-010 rc=0이 같은 결론이다.
|
||||
- 그룹 밖에서 adapter로 가는 edge 17개: 모두 그룹 `index.ts`(platform 배럴 포함)로 간다. 서브배럴이나 2단계 index로 가는 것은 없다.
|
||||
- adapter 그룹 16개: 모두 `index.ts`가 있다. `bbde570` 뒤로 배럴 표면 변경은 0이다.
|
||||
- `storage/*`가 `browser-file-storage/result.ts`를 import한다: `storage/indexeddb`·`storage/opfs`에서만이다. 제거 드릴이 함께 지우는 묶음이라 드릴을 깨지 않는다.
|
||||
- `REFUSALS_OF_EVERY_ATTEMPT`(`src/contracts/errors.ts:256`)가 `REFUSED_BEFORE_WRITE`의 두 행을 손으로 옮겼다: `tests/unit/backend-envelope.test.ts:187-205`가 양쪽을 대조한다. 위치는 D10 보완 결정의 판정 자리다(`decisions.md` 2.2절). 손 사본이 아직 같고 대조 시험이 있어 결함이 아니다.
|
||||
- kernel 폴더의 bootstrap 전용 서비스 둘(`browser-lifecycle.ts`, `browser-mutation-intent-factory.ts`): 1101/05-04 "고쳐짐 유지"(잔여 위험 기록)다. adapter의 import는 지금도 0이다. 다시 올리지 않는다.
|
||||
- `createHttpObservationProjector`와 `isTerminalNonAbortFailure`가 bootstrap에 있다: VD-07 결정 기록이 정한 유일한 projection 자리다.
|
||||
- 규칙과 문서에는 있는데 폴더가 없는 것: `src/adapters/web-worker`는 의도해서 비워 둔 자리다(`verify-documentation-readiness.ts:168-173` `NOT_CREATED`, 매뉴얼 03 189행). `src/domain`은 "지금은 없다"고 적혀 있다.
|
||||
- `../../../clean-architecture-backend-template/…` 링크: 문서 검사가 pin 커밋의 tree로 확인하는 의도된 형식이다(`verify-documentation-readiness.ts:228-275`).
|
||||
- facade 자신을 뺀 `pathNot`(lucide·zod·외부 계약·관측·loaded-feature-runtimes 자신)에 재검토 조건이 없다: 이것들은 단일 입구를 정의하는 것이지 예외가 아니다. `layers.md`도 예외 목록에 넣지 않는다.
|
||||
- realtime을 고르면 템플릿 소유 규칙(`unselected-realtime-runtime-is-not-composed`)을 고쳐야 한다는 의심(S4): 지금은 조립이 realtime 선택 자체를 거절한다(`src/features/product-capabilities.ts:24-25`, 매뉴얼 03 185행). 막히는 지원 경로가 없다.
|
||||
- `src/contracts`가 `src/platform`만 import하고 반대 방향은 0이다: `contract-ownership.md:34`와 같다.
|
||||
- `bbde570` 뒤 공개 표면 변경(`server-state.ts`의 `resendSafe`): 선택 필드와 반환 필드를 더한 것뿐이라 BREAKING이 필요 없다.
|
||||
- `check-architecture.ts`의 R2 변경(`inspectTypeScriptOnlyPolicy`): 등록부에서 고른 루트가 이전 하드코딩(src·scripts·tests·.storybook, 선택 recipes)과 같다.
|
||||
- INVENTORY 행 집합: 추적 파일 143개와 정확히 같고 중복이 없다.
|
||||
- 백엔드 생성 create와 `--keyed`: 매뉴얼이 "백엔드 create를 멱등성 executor 뒤에 둔 뒤에 쓴다"고 적는다(`docs/manual/reference/create-feature.md:18`). 알려진 전제라 결함이 아니다.
|
||||
- 지시문 주입: 읽은 코드·문서에 리뷰어를 겨냥한 지시는 없었다.
|
||||
@@ -0,0 +1,232 @@
|
||||
# round9 L3 — 시험(fe-testing·fe-qa) 전체 리뷰
|
||||
|
||||
> round9 리뷰(2026-11-12, 대상 main `5250ff95`)의 영역 기록이다. 서브에이전트가 쓴 원문을 그대로 옮겼다. 바꾼 것은 이 인용 블록과, 작업 폴더 절대 경로를 `(작업 폴더)`로 줄인 것뿐이다. 발견 ID는 이 파일의 이름표(R-01 등)이고, 라운드 ID(`1112/NN-MM`)와의 대응은 [README](2026-11-round9-review.md) 15절이다.
|
||||
|
||||
|
||||
대상: `5250ff95`(tree `75cc3752`, origin/main). 노트북 worktree에서 읽기만 했다. repo 파일은 고치지 않았다. desktop은 `/tmp/claude-gates/r9fe-base/summary.txt`만 읽었다.
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- 판정: **고칠 것 있음.** High 이상 0건. Medium 1건, Low 8건, 개선 제안 1묶음.
|
||||
- 특별 확인 후보(W1의 preload 말): **템플릿에는 해당하지 않는다.** 템플릿 fixture는 쓰이지 않은 preload를 세 엔진에서 직접 검사한다. WebKit 추정 경고는 문구 하나만 정확히 일치할 때 무시한다. 응답을 가로채는 CSP spec은 `fulfillBuildScript`를 쓴다. SW가 제어하는 문서는 `preloadunverifiable:service-worker:`로 이름 붙여 실패시키고, 그 줄은 SW update spec에서만 허용한다. tech-log main(`7a4e201a`)에는 `preload-use.ts`가 아예 없다. strict fixture도 `NO_COLOR`만 무시한다. 그래서 W1의 말은 tech-log가 이 파일을 아직 옮기지 않은 상태(또는 tech-log의 다른 작업본)를 본 것으로 판단한다. 5절 첫 줄에 근거를 적었다.
|
||||
- 가장 큰 것: 감소된 움직임(reduced-motion) e2e가 `body`의 `animation-duration`을 보는데, 허용 값에 초기값 `"0s"`가 들어 있다. 그래서 규칙을 지워도 통과한다(T-01, Medium).
|
||||
|
||||
## 1. 범위
|
||||
|
||||
| 항목 | 내용 |
|
||||
|---|---|
|
||||
| 렌즈 | `.claude/skills/fe-testing/SKILL.md`(함정 12, 점검표), `.claude/skills/fe-qa/SKILL.md`(함정 10, 회귀 점검표). 더해서 시험 GWT(준비 조건·행동·기대 결과가 드러나는가). GWT 표기 규칙은 이 repo에 없다(`docs/work/reference/testing.md` 전체 확인). 그래서 렌즈와 testing.md가 요구하는 것을 어긴 것만 결함으로 봤고, 나머지는 개선 제안으로 건수와 대표 위치만 적었다 |
|
||||
| 기준 문서 | `docs/work/reference/testing.md` 전체, `docs/work/reference/defect-patterns.md` 2절(T1~T10)과 G7·G9, `docs/work/reference/review-criteria.md` 2·3·5·8절, `docs/work/reference/decisions.md`, `.claude/rules/tests.md`, `docs/testing/taxonomy.md` |
|
||||
| 바뀐 곳 먼저 | `git diff --stat bbde570 5250ff95 -- tests vitest.config.ts 'playwright*.config.ts' config/testing config/ci/ungated-tests.json scripts/run-vitest.ts scripts/check-test-evidence.ts`: 201파일, +5,615/−5,137. 참조 기능 시험 22파일 삭제(`e3c8db48`), 생성 기능 e2e 신설, 갤러리 시험을 Storybook으로 이동, 자식 프로세스 timeout 규칙(`91962e24`) |
|
||||
| 전부 읽음 | `tests/support/browser/preload-use.ts`, `strict-browser-test.ts`, `tests/e2e/preload-use.spec.ts`, `production-csp.spec.ts`, `service-worker-update.spec.ts`, `service-worker-recovery.spec.ts`, `boot-module-failure.spec.ts`, `old-tab-chunk-recovery.spec.ts`, `generated-feature.spec.ts`, `accessibility.spec.ts`, `scroll-restoration.spec.ts`, `typography.spec.ts`, `theme.spec.ts`, `tests/storybook/galleries.spec.ts`, `tests/visual/platform.visual.spec.ts`, `tests/browser-capabilities/chunk-load-error.spec.ts`, `tests/e2e/support/fixture-builds.ts`, `service-worker-builds.ts`(1~120), `vitest.config.ts`, `tests/setup.ts`, `tests/helpers/child-process-timeout.ts`, `tests/unit/child-process-timeout.test.ts`, `scripts/run-vitest.ts`, `scripts/check-test-evidence.ts`, `scripts/lib/no-skipped-tests-reporter.ts`, `scripts/lib/ungated-tests.ts`, `config/ci/ungated-tests.json`, `tests/unit/test-evidence-source-rules.test.ts`, `tests/mocks/server.ts`, Playwright 설정 5개 중 e2e·capabilities·storybook |
|
||||
| 부분 읽음 | `tests/component/application-mutation-admission.test.tsx`(diff), `tests/integration/provider-guardian-transaction.test.ts`(`77c01b03` diff), `tests/browser-capabilities/opfs-runtime.spec.ts`(1~40, 180~275, 335~420), `cross-context-invalidation.spec.ts`(155~210), `indexeddb-runtime.spec.ts`(925~945), `image-cdn.spec.ts`(100~170), `storage-manager.spec.ts`, `browser-files.spec.ts`(450~470), `tests/unit/deletable-history-documents.test.ts`(1~80), `a11y-report.test.ts`(이름), `runtime-adapters-auth-profile.test.ts`(360~420), `scripts/scale/run-scale-profile.ts`, `scripts/scale/measure-feature-shape-growth.ts`(280~330), `scripts/test-feature-scaffold.ts`(60~100), `scripts/lib/build-environment.ts`, `src/adapters/http/backend-envelope.ts`(170~215), 짝 백엔드 `docs/web/http-contract.md` 4절·`docs/registries/error-codes.yaml` |
|
||||
| fe-testing 기준으로 본 것 | 층 배치(바뀐 파일), MSW strict(`onUnhandledRequest: "error"` 4곳, `vi.fn()` fetcher는 "보내지 않음" 단언용만), 흔들림(실제 시계 대기, 고정 대기), 거짓 통과(이른 return, 초기값 허용, 허용 패턴 범위), 검출력(변이 예측), 검사기의 음성 fixture, 게이트 연결(ungated 6건 사유, 스크립트 경로 대조 377파일), timeout 규칙 |
|
||||
| fe-qa 기준으로 본 것 | 로딩 화면 대신 라우트 h1을 기다리는가, 템플릿 원래 상태 밖(생성 기능 빌드) 시험, 실패·결과 불명·재전송 흐름, 두 탭, 콘솔 오류 처리(strict fixture 우회 지점), MSW·대역 응답이 짝 백엔드와 같은가 |
|
||||
| 게이트 실행 결과(읽기만) | `summary.txt`: tree가 HEAD와 같다. FE-GATE-001~012 rc=0(008 201 s, 009 32 s), FE-GATE-013 rc=1(D8 판정 대상, 이 렌즈 몫 아님), FE-GATE-020 진행 중. 게이트 로그는 `PASS` 한 줄뿐이고 `snapshot/`이 아직 없다 |
|
||||
| 확인 못 한 것 | (1) e2e·capability의 엔진별 통과·skip 수: snapshot 없음. (2) OPFS 05-01 시험이 어느 엔진에서 이른 return 하는지: 실행해야 안다(E-02). (3) 참조 기능 시험 약 3,000줄이 지키던 플랫폼 동작이 모두 옮겨졌는지 전수 대조하지 않았다. 표본 9개(sign-out 판정, intent 비노출, 중복 제거, fan-out, retry 겹침 등)는 대응 시험이 있다. (4) FE-GATE-029(`check:ci:gating`)는 main 단계라 이번 실행에 없다(E-05). (5) `tests/unit` 대부분과 `tests/component`·`tests/integration`의 바뀌지 않은 파일은 표본만 봤다 |
|
||||
|
||||
## 2. 발견
|
||||
|
||||
### T-01 감소된 움직임 e2e가 규칙을 지워도 통과한다
|
||||
|
||||
| 칸 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함(거짓 통과, 코드로 확정. 실행 확인은 E-01) |
|
||||
| 관련 관점 | 10, 21, 5 |
|
||||
| 심각도·우선순위 | Medium · P2. 이 정책을 지키는 시험은 이것 하나다. 라우트 수동 검토 문서가 이 시험을 자동 증거로 적는다. 지금 규칙은 있어서 사용자 피해는 없다 |
|
||||
| 통제 | 규칙 「동작 줄이기 설정이면 꼭 필요하지 않은 움직임을 멈춘다」: 목표 M3 / 확인 M2(CSS 규칙은 있다, 자동 검사는 효과 없음) |
|
||||
| 증거 | E1 |
|
||||
| 근거 | `tests/e2e/accessibility.spec.ts:130-137`이 `body`의 `getComputedStyle(body).animationDuration`을 읽고 `["0s", "0.00001s", "1e-05s"]` 안에 있으면 통과다. `body`에는 animation이 없다. 앱의 animation은 `.ui-spinner` 하나다(`src/presentation/styles/theme/primitives.css:108-117`, `ui-spin … infinite`). 규칙(`src/presentation/styles/theme/responsive.css:86-95`)이 없으면 `body`의 값은 초기값 `"0s"`이고, 이 값이 허용 목록에 있다. 다른 검사도 없다(`git grep -i "reduced-motion\|reducedMotion\|prefers-reduced" -- tests scripts eslint.config.ts config .storybook`: 이 시험 하나). `docs/accessibility/route-reviews/APP_HOME.md:18`은 "Automated … reduced-motion evidence is available"이라 적는다 |
|
||||
| 발생 조건 | 누가 `responsive.css`의 미디어 블록을 지우거나 `*` 선택자를 좁히거나, 새 animation이 `!important` 규칙 밖에 생길 때 |
|
||||
| 영향 | 전정 장애 사용자에게 움직임이 그대로 나가도 FE-GATE-008·009가 통과한다. 수동 검토(M7)는 아직 pending이라 뒤를 받치지 못한다 |
|
||||
| 최소 개선 방향 | 움직이는 실제 요소를 본다. 같은 시험에서 스피너가 있는 화면(또는 페이지에 `.ui-spinner`를 하나 붙여)을 열고, 감소 설정 없을 때 `animation-iteration-count`가 `infinite`임을 먼저 단언한 뒤(전제), 감소 설정에서 `1`이고 duration이 0.01ms 이하임을 단언한다. 허용 목록에서 초기값 `"0s"`를 뺀다 |
|
||||
| 완료 기준 | `responsive.css:86-95`를 지우는 변이에서 이 시험이 세 엔진 모두 실패한다. 변이 없이 세 엔진 통과 |
|
||||
| RED 시험 아이디어 | 위 "전제 + 감소" 두 단언 시험. 지금 코드에서는 통과(규칙 있음), 변이를 넣으면 실패. 지금 시험은 변이에서도 통과(E-01로 확인) |
|
||||
|
||||
### T-02 OPFS 05-01 브라우저 시험이 OPFS를 못 쓰면 단언 없이 통과하고, 증거는 "zero skipped"라 적는다
|
||||
|
||||
| 칸 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험(코드 모양은 확인) + 미검증(지금 그렇게 끝나는 엔진이 있는지) |
|
||||
| 관련 관점 | 10, 21, 5 |
|
||||
| 심각도·우선순위 | Low · P2. E-02에서 한 엔진이라도 이른 return이면 Medium · P1로 올린다(증거 검사가 틀린 답을 낸다, `review-criteria.md` 3절) |
|
||||
| 통제 | 「skip은 quarantine으로만」: M3(`check-test-evidence.ts`)지만 `return`은 skip으로 세지 않아 이 자리에는 M1 |
|
||||
| 증거 | E1 |
|
||||
| 근거 | `tests/browser-capabilities/opfs-runtime.spec.ts:352`와 `:470`이 `if (!(await installOpfsTab(page, scope))) return;`이다. `installOpfsTab`은 지원 판정이 거절이면 `false`를 낸다(`:252`). 그때 두 시험(3 케이스)은 단언 0개로 passed가 된다. 같은 파일 첫 시험은 미지원이면 `UNSUPPORTED`를 단언한다(`:186-191`). 증거 검사는 junit의 `<skipped>`만 보고 "zero skipped"를 찍는다(`scripts/verify-browser-capability-evidence.ts:61-62`, `:72`). 1105 리뷰는 WebKit이 기본 정책에서 거절돼 spec이 일찍 끝난다고 적었고(`docs/reviews/2026-11-05-maturity-review/05-adapters-storage-kernel.md:164`), 1106 리뷰는 실행 시간으로 보아 돈 것 같다고 추론만 했다(`docs/reviews/2026-11-06-maturity-review/11-tests-browser-release-scale.md:203`). 두 라운드 연속 「확인 못 한 것」으로 넘어왔다 |
|
||||
| 발생 조건 | OPFS 지원 판정(`inspectBrowserOpfsSupport`, `src/adapters/storage/opfs/browser-opfs-runtime.ts:151-180`)이 거절하는 엔진·버전 |
|
||||
| 영향 | 그 엔진에서 "다른 탭 purge가 진행 중 put을 기다린다"(1103/05-01 수정)를 아무도 보지 않는데 증거는 세 엔진 통과로 남는다 |
|
||||
| 최소 개선 방향 | 이른 return 대신, 지원해야 하는 엔진에서는 `expect(await installOpfsTab(...)).toBe(true)`로 단언한다. 지원하지 않는 엔진이 정말 있으면 `test.skip(<엔진 조건>, 이유)` + quarantine 주석으로 이름을 남긴다(그러면 증거 검사가 skip으로 센다) |
|
||||
| 완료 기준 | 두 자리에 조용한 `return`이 없다. E-02 패치(그 자리에서 실패시키기)에서 세 엔진 결과가 기록되고, 미지원 엔진은 skip으로 증거에 나타난다 |
|
||||
| RED 시험 아이디어 | E-02의 패치 그대로. 미지원 엔진이 있으면 지금 그 엔진에서 실패한다 |
|
||||
|
||||
### T-03 `check-test-evidence.ts`의 규칙 셋에 혼자 도는 거절 fixture가 없다
|
||||
|
||||
| 칸 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함(검사기 자기 보호 없음, 결함 패턴 G9) |
|
||||
| 관련 관점 | 21, 10 |
|
||||
| 심각도·우선순위 | Low · P2. FE-GATE-008이 돌리는 시험 품질 검사의 일부가 꺼져도 아무 게이트도 모른다 |
|
||||
| 통제 | M1(규칙은 있고, 규칙을 지키는 시험은 없음) |
|
||||
| 증거 | E1 |
|
||||
| 근거 | (1) 화면 전체 mask 규칙(`scripts/check-test-evidence.ts:307-311`): fixture `tests/fixtures/test-evidence/forbidden/full-screen-mask.fixture`가 있지만, 혼자 돌리는 시험이 없다. `tests/unit/test-evidence-source-rules.test.ts:31-32` 주석은 "Each forbidden fixture is checked alone"이라 적지만 시험은 셋(focused·expired·unowned, `:34-50`)뿐이다. 디렉터리 전체를 돌리는 FE-GATE-029 명령은 기대 진단이 공통 접두어 `"Test evidence failed:"`(`config/ci/gates.json:118` 행)라, 다른 fixture 셋이 계속 실패하면 통과한다. (2) strict fixture 우회 규칙(`:391-399`)과 (3) Playwright 설정의 `forbidOnly` 확인(`:385-389`)은 `if (!fixtureMode && !scenarioOnly)`(`:368`) 안에 있어 fixture 모드에서 아예 돌지 않는다. 이 두 문구를 찾는 시험도 없다(`git grep -n "bypasses strict browser fixture\|missing forbidOnly" -- tests`: 0건) |
|
||||
| 발생 조건 | 셋 중 한 규칙을 지우거나 정규식을 좁히는 변경 |
|
||||
| 영향 | 화면 전체를 가린 시각 시험, strict fixture를 우회한 e2e spec이 FE-GATE-008을 통과한다 |
|
||||
| 최소 개선 방향 | `test-evidence-source-rules.test.ts`에 mask fixture 하나만 돌리는 시험을 더한다. e2e 규칙 둘은 검사 대상 폴더·설정을 인자로 받게 하고(`--e2e-root`, `--playwright-config`), 우회 spec 하나와 `forbidOnly` 없는 설정 하나를 거절 fixture로 둔다 |
|
||||
| 완료 기준 | 세 규칙 각각을 지우는 변이에서 시험이 하나씩 실패한다 |
|
||||
| RED 시험 아이디어 | "rejects a screenshot mask over the whole UI": mask fixture 단독 실행이 rc=1과 `screenshot mask may not cover the whole UI`를 낸다. 지금은 시험이 없어서 E-03 변이(`:309-311` 삭제)가 살아남는다 |
|
||||
|
||||
### T-04 strict fixture 강제가 `tests/e2e`의 문자열 포함 검사뿐이다
|
||||
|
||||
| 칸 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험(결함 패턴 G8) |
|
||||
| 관련 관점 | 21, 23 |
|
||||
| 심각도·우선순위 | Low · P3. 지금 우회하는 spec은 `chunk-load-error.spec.ts` 하나이고 이유가 있다 |
|
||||
| 통제 | M3(e2e 폴더, 문자열) / M1(나머지 브라우저 폴더) |
|
||||
| 증거 | E1 |
|
||||
| 근거 | `scripts/check-test-evidence.ts:391-399`는 `tests/e2e/*.spec.ts`의 본문에 `"support/browser/strict-browser-test"` 글자가 있는지만 본다. 주석에 그 경로만 적어도 통과하고, 한 파일에서 맨 `test`를 섞어 써도 통과한다(`tests/e2e/preload-use.spec.ts:4`, `:111`, `:122`는 의도한 혼용). `tests/browser-capabilities`·`tests/visual`·`tests/storybook`은 검사하지 않는다. `tests/browser-capabilities/chunk-load-error.spec.ts:1`이 맨 `@playwright/test`를 쓴다(지난 리뷰가 이유를 받아들였다) |
|
||||
| 발생 조건 | 새 capability·visual spec이 맨 `test`를 쓰거나, e2e spec이 주석에만 경로를 남길 때 |
|
||||
| 영향 | 그 spec에서 콘솔 오류·pageerror·preload 검사가 조용히 빠진다(fe-qa 함정 9) |
|
||||
| 최소 개선 방향 | ESLint `no-restricted-imports`로 `tests/{e2e,browser-capabilities,visual,storybook}/**/*.spec.ts`에서 `@playwright/test`의 값 `test` import를 막고, 의도한 파일 둘(`preload-use.spec.ts`, `chunk-load-error.spec.ts`)만 이유를 단 예외로 둔다. 문자열 검사는 지운다 |
|
||||
| 완료 기준 | 맨 `test`를 쓰는 새 spec이 네 폴더 어디서든 lint에서 실패한다. 거절 fixture가 있다 |
|
||||
| RED 시험 아이디어 | `tests/fixtures/architecture` 방식의 lint fixture: capability 폴더 spec 하나가 `import { test } from "@playwright/test"` → 지금은 아무 게이트도 실패하지 않음 |
|
||||
|
||||
### T-05 두 번째 탭과 자기 context는 strict 검사 밖이다
|
||||
|
||||
| 칸 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관련 관점 | 10, 12 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제 | M2(첫 `page`만) |
|
||||
| 증거 | E1 |
|
||||
| 근거 | strict fixture는 fixture의 `page` 하나에만 listener와 preload 추적을 붙인다(`tests/support/browser/strict-browser-test.ts:68-96`). 앱을 여는 두 번째 탭 7곳은 콘솔 오류·pageerror·requestfailed를 아무도 보지 않는다: `cross-context-invalidation.spec.ts:163`, `:226`, `opfs-runtime.spec.ts:341`, `:459`, `indexeddb-runtime.spec.ts:933`, `:985`, `:1190`. `tests/e2e/service-worker-recovery.spec.ts:94-150`은 고장 단계 때문에 자기 context를 쓰고 회복된 load만 손으로 검사한다. 그 검사는 preload 검사가 없고, WebKit 문구 무시도 없어 fixture와 갈라진 사본이다(`:135-150`). 회복된 문서는 SW 제어가 없다고 단언하므로(`:147-149`) `trackPreloadUse`를 붙일 수 있다 |
|
||||
| 발생 조건 | 두 탭 경쟁 시험에서 두 번째 탭이 오류를 내는 회귀(fe-qa 함정 8의 자리) |
|
||||
| 영향 | 두 탭 시나리오의 회귀가 첫 탭의 단언만으로 통과한다 |
|
||||
| 최소 개선 방향 | strict 검사 본문을 `watchBrowserFailures(page)` 함수로 빼서 fixture와 두 번째 탭이 같이 쓰게 한다(같은 판정 `judge`). SW recovery는 마지막 `goto` 전에 그 함수와 `trackPreloadUse`를 붙인다 |
|
||||
| 완료 기준 | 두 번째 탭에서 `console.error`를 내는 변이에서 그 시험이 실패한다. 손으로 쓴 검사 사본이 없다 |
|
||||
| RED 시험 아이디어 | `cross-context-invalidation.spec.ts`의 두 번째 탭에서 `secondPage.evaluate(() => console.error("probe"))` → 지금은 통과 |
|
||||
|
||||
### T-06 old-tab 시험의 preload 허용 절반이 닿지 않는 문서를 가리키고, 주석이 fixture 동작과 다르다
|
||||
|
||||
| 칸 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험(허용이 일으킨 실패보다 넓다) |
|
||||
| 관련 관점 | 10, 9 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제 | M2 |
|
||||
| 증거 | E1 |
|
||||
| 근거 | 허용 정규식이 "A 탭에서 A 플랫폼 화면과 함께 preload된 청크"를 `preloadunused:` 허용에 넣는다(`tests/e2e/old-tab-chunk-recovery.spec.ts:181-188` 주석, `:195`). 그러나 preload 검사는 끝에 열려 있는 문서만 본다(`tests/support/browser/preload-use.ts:34-35`, `:217`). A 탭은 reload로 B 문서가 된다(`:241` `loads === 1`). 그래서 A 목록은 A 문서에 쓰일 일이 없고, B 문서에 같은 이름(공유 청크)으로 나타나는 "정말 안 쓴 preload"만 가릴 수 있다 |
|
||||
| 발생 조건 | B 문서에서 공유 청크 preload가 실행되지 않는 회귀 |
|
||||
| 영향 | 그 회귀를 이 시험이 놓친다. 지금 가린 실패는 없다(추론) |
|
||||
| 최소 개선 방향 | A 목록을 지우고 B context routes 모듈 목록만 남긴다. 주석을 "B 탭의 것만"으로 고친다 |
|
||||
| 완료 기준 | E-04에서 A 목록 없이 세 엔진 반복 통과 |
|
||||
| RED 시험 아이디어 | 해당 없음(허용 축소). 축소 뒤 통과가 근거다 |
|
||||
|
||||
### T-07 [w2-fe-2 파일] `ungated-tests.json`의 사유가 파일에 맞지 않는다 — 특히 순수 parser 시험
|
||||
|
||||
| 칸 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함(기준을 낮춘 예외의 사유가 사실과 다름). 0929부터 ID 없이 이월된 항목이고, 지금도 같다 |
|
||||
| 관련 관점 | 21, 10, 26 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제 | M3(`check:ci:gating`이 목록에 없는 파일은 잡는다) / 사유 내용은 M0 |
|
||||
| 증거 | E1 |
|
||||
| 근거 | 6건 모두 같은 사유("baseline-regression이 기록한 CPU에서만 시간을 비교")다(`config/ci/ungated-tests.json`). 이 사유는 tier를 CI에서 안 도는 이유이지, 파일을 게이트에서 빼는 이유가 아니다. `tests/scale/tsc-diagnostics-parser.test.ts`(`:25`)는 문자열을 parse하는 순수 시험이다(`tests/scale/tsc-diagnostics-parser.test.ts:8-45`). 그 parser는 merge 게이트가 돌리는 측정이 쓴다(`scripts/scale/measure-feature-shape-growth.ts:307`, FE-GATE-020의 `scripts/test-feature-scaffold.ts:76-80`). 나머지 다섯도 개수·상한·가짜 시계를 단언한다(`tests/scale/session/long-session.test.ts:75`, `:149-150`, `network-flap.test.ts:88`, `telemetry-storm.test.ts:79-84`). 1103 리뷰의 변이 H57을 잡은 시험은 `long-session.test.ts` 하나였다(`docs/reviews/2026-11-03-maturity-review/10-tests-fast-layers.md:138`) |
|
||||
| 발생 조건 | parser나 세션·telemetry 상한을 깨는 변경 |
|
||||
| 영향 | merge 게이트 측정이 쓰는 parser의 오해석, 세션 정리 회귀를 merge에서 못 본다 |
|
||||
| 최소 개선 방향 | `tsc-diagnostics-parser.test.ts`를 게이트 경로(예: `tests/unit` 또는 `test:coverage` 목록)로 옮기고 항목을 지운다(`ungatedTestFailures`가 남은 항목을 stale로 잡는다, `scripts/lib/ungated-tests.ts:104-106`). 나머지 다섯은 파일마다 실제 사유(실행 시간, 자식 프로세스 등)를 적거나 pr tier로 옮긴다. 결정이 필요하면 `decisions.md` 3절 형식으로 남긴다 |
|
||||
| 완료 기준 | 남은 항목마다 그 파일에 맞는 사유가 있다. parser 시험이 merge 게이트에서 돈다 |
|
||||
| RED 시험 아이디어 | parser의 `M` 단위 변환(`collect-tsc-diagnostics.ts` `value * 1024`)을 바꾸는 변이 → 지금 merge 게이트 어디서도 실패하지 않음. 옮긴 뒤 FE-GATE-005에서 실패 |
|
||||
|
||||
### T-08 [w2-fe-2 관련: 시험 timeout] 새 timeout 규칙 밖에 손으로 정한 숫자 54곳과 옛 상수 4벌이 남았고, taxonomy가 옛 방식을 예로 든다
|
||||
|
||||
| 칸 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함(문서와 코드가 다름, 갈라진 사본) |
|
||||
| 관련 관점 | 9, 23, 10 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제 | M3(기본 timeout + 자식 프로세스는 `tests/setup.ts`가 막음) / 숫자의 근거는 M1 |
|
||||
| 증거 | E1 |
|
||||
| 근거 | `docs/work/reference/testing.md` 2절은 "값은 desktop에서 잰 가장 긴 실행으로 정한다: `childProcessTimeout(<ms>)`"라 적는다. `91962e24` 본문은 "시험마다 손으로 정한 숫자"를 근거가 없다고 버렸다. 그러나 기본값이 아니라서 가드에 걸리지 않는 손 숫자가 54곳 남았다(`git grep -nE "\}, [0-9]{2,3}_000\);\|\{ timeout: [0-9]{2,3}_000 \}" -- 'tests/**/*.test.ts' 'tests/**/*.test.tsx'`, 예: `tests/unit/test-evidence-source-rules.test.ts:38`, `tests/system/ci-runner/ci-artifact-contract.test.ts` 16곳). `PROCESS_HEAVY_TIMEOUT_MS = 30_000`이 네 파일에 따로 있다(`tests/unit/risk-coverage.test.ts:34`, `tests/unit/security-followup-fixture.ts:26`, `tests/integration/provider-guardian-transaction.test.ts:28`, `tests/system/ci-runner/ci-artifact-contract.test.ts:65`). `docs/testing/taxonomy.md:104-106`은 여전히 `PROCESS_HEAVY_TIMEOUT_MS`를 예로 든다 |
|
||||
| 발생 조건 | 새 시험 작성자가 taxonomy를 따라 상수를 복사할 때 |
|
||||
| 영향 | 같은 문제(부하 desktop의 자식 프로세스 시험)에 두 규칙이 있고, 한쪽은 근거가 남지 않는다 |
|
||||
| 최소 개선 방향 | 54곳과 상수 4벌을 `childProcessTimeout(<잰 ms>)`로 바꾸거나, 이미 잰 값이면 그 값을 인자로 적는다. taxonomy 예시를 helper로 고친다 |
|
||||
| 완료 기준 | 자식 프로세스 시험의 timeout이 모두 helper를 거친다. taxonomy와 testing.md가 같은 방법을 적는다 |
|
||||
| RED 시험 아이디어 | 해당 없음(규칙 통일). 원하면 `tests/setup.ts` 가드를 "helper가 만든 값이 아닌 timeout"까지 넓히는 시험 |
|
||||
|
||||
### T-09 생성 기능 e2e의 오류 응답이 "짝 백엔드의 Envelope"라는 주석과 다르다
|
||||
|
||||
| 칸 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험(대역이 실제 상대와 다름, 결함 패턴 T6). 지금은 판정이 status로만 정해져 결과가 같다 |
|
||||
| 관련 관점 | 17, 10 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제 | M1 |
|
||||
| 증거 | E1 |
|
||||
| 근거 | 주석: "The API answers are the paired backend's Envelope"(`tests/e2e/generated-feature.spec.ts:26-27`). 429 답은 `code: "RATE_LIMITED"`, `category: "SYSTEM"`(`:62-68`, `:246`)이다. 짝 백엔드는 `RATE_LIMIT_EXCEEDED`, `category: RATE_LIMIT`, `Retry-After`다(백엔드 `docs/registries/error-codes.yaml:371-375`, `docs/web/runbook.md:8`). 500 답은 `INTERNAL_ERROR` + `SYSTEM`(`:284`)인데 백엔드는 `category: INTERNAL`이다(`error-codes.yaml:835-838`). 프론트의 429 판정은 status로만 한다(`src/contracts/errors.ts:326`, `src/adapters/http/http-execution-v3.ts:1300-1309`). 쓰기 전 거절 표는 code로 본다(`src/adapters/http/backend-envelope.ts:168-193`) |
|
||||
| 발생 조건 | 프론트가 429·500의 code나 category를 읽게 되는 변경(예: 429 code별 안내) |
|
||||
| 영향 | 브라우저 흐름이 존재하지 않는 code로 통과한다 |
|
||||
| 최소 개선 방향 | `failure()` 두 호출을 백엔드 표의 code·category로 바꾼다. 가능하면 `config/contracts/`의 짝 계약 사본에서 읽는다 |
|
||||
| 완료 기준 | e2e의 오류 Envelope가 짝 백엔드 registry 행과 같다 |
|
||||
| RED 시험 아이디어 | 해당 없음(대역 교정) |
|
||||
|
||||
### T-10 `@a11y` 브라우저 시험을 merge가 두 번 돈다
|
||||
|
||||
| 칸 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 개선 제안(실행 비용). 1101/10-06(빠른 층, 결정 대기)과 같은 모양의 브라우저 층 자리 |
|
||||
| 관련 관점 | 14, 20 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제 | 해당 없음 |
|
||||
| 증거 | E1 + 이번 실행 시간(FE-GATE-009 32 s, desktop, summary.txt) |
|
||||
| 근거 | FE-GATE-008의 `test:e2e`는 `playwright test` 전체다(`package.json:43`). FE-GATE-009의 `test:a11y`는 `--grep @a11y`를 다시 돈다(`package.json:58`). `@a11y` 시험은 `tests/e2e/accessibility.spec.ts`와 `tests/e2e/generated-feature.spec.ts:351-370`이다. 009는 webServer 빌드를 한 번 더 하고, 생성 기능 spec의 `beforeAll` 사본 빌드도 다시 돈다. `docs/work/reference/testing.md` 6절은 "merge 단계가 같은 파일을 두 번 돌리지 않는지 본다"고 적는다 |
|
||||
| 최소 개선 방향 | `test:e2e`에 `--grep-invert @a11y`를 주고 접근성은 009 하나에서만 센다. 또는 두 번 도는 이유를 1101/10-06 결정에 같이 적는다 |
|
||||
| 완료 기준 | 한 merge에서 `@a11y` 시험이 엔진마다 한 번 돈다 |
|
||||
| RED 시험 아이디어 | 해당 없음 |
|
||||
|
||||
### 개선 제안 묶음 (GWT와 작은 것)
|
||||
|
||||
| 무엇 | 건수 | 대표 위치 |
|
||||
|---|---|---|
|
||||
| 이름이 본문에 없는 동작을 말한다 | 1 | `tests/storybook/galleries.spec.ts:74` "duplicate toast" — 토스트를 한 번만 띄운다. 중복 처리는 `tests/component/design-system-platform.test.tsx:216`이 본다 |
|
||||
| 한 시험이 독립된 행동 여럿을 섞어 실패 위치가 흐리다 | e2e·capability 7곳 이상 | `tests/e2e/theme.spec.ts:4`(axe 스캔 + 저장 유지), `tests/storybook/galleries.spec.ts:74`(메뉴·토스트·탭), `tests/browser-capabilities/indexeddb-runtime.spec.ts:256`, `opfs-runtime.spec.ts:3`, `public-cache-storage.spec.ts:3`, `browser-files.spec.ts:14` |
|
||||
| 이름에 여러 경우를 쉼표·and/or로 나열(한 시험에 여러 입력) | Vitest·Playwright 이름 137개(전체 `it/test` 약 2,820 + e2e 56 중, 휴리스틱) | `tests/unit/docs-system.test.ts:181`, `tests/unit/repository-layout.test.ts:59`. `it.each`로 나누면 실패한 경우가 이름에 나온다 |
|
||||
| 부재 단언을 고정 대기로 한다(신호 없음) | 5 | `tests/e2e/app-shell.spec.ts:65`(300 ms), `tests/browser-capabilities/cross-context-invalidation.spec.ts:201`, `:270`(100 ms), `opfs-runtime.spec.ts:413`, `:512`(250 ms). 부하에서 늦게 온 사건은 통과 쪽으로 빠진다. 뒤에 보낸 표지 메시지를 기다린 뒤 "앞 메시지가 없다"를 단언하는 식으로 바꾼다 |
|
||||
| 콘솔 warning 무시가 부분 문자열이다 | 1 | `tests/support/browser/strict-browser-test.ts:22` `includes("NO_COLOR")`. 출처 주석이 없다. WebKit 문구처럼 정확 일치로 좁히거나 출처를 적는다 |
|
||||
|
||||
## 3. 넘길 것
|
||||
|
||||
- → fe-a11y: T-01에서 "꼭 필요하지 않은 움직임"의 범위(스피너는 멈춰야 하나, 회전만 줄이나)와 M7 수동 기록 문구(`docs/accessibility/route-reviews/APP_HOME.md:18`)가 맞는지. 시험 검출력은 이 렌즈 몫, 정책 내용은 그쪽 몫이다.
|
||||
- → fe-structure(또는 게이트 담당): T-04의 ESLint 규칙 범위와 예외 두 파일.
|
||||
- → 총괄(게이트 결정): T-07의 남은 다섯 scale 파일을 pr tier로 옮길지, 사유만 고칠지. T-10은 1101/10-06 결정 대기에 같이 붙일지.
|
||||
- → 백엔드 repo 세션(총괄 경유): 해당 없음. T-09는 백엔드 registry를 읽기만 했고 프론트 쪽 교정이다.
|
||||
- → 결정 대기 D11(생성 기능 설치 상태의 브라우저 merge 게이트): 참조 기능 삭제(`e3c8db48`) 뒤 템플릿에는 `session-required` 라우트가 없다. 그래서 `tests/e2e/accessibility.spec.ts:48-88`의 보호 라우트 분기와 `notChecked` 기록은 템플릿 게이트에서 한 번도 돌지 않는다. 로직은 `tests/unit/a11y-report.test.ts:110-197`이 fixture descriptor로 본다. D11이 정할 일이라 새 발견으로 세지 않았다.
|
||||
|
||||
## 4. 실험 요청
|
||||
|
||||
모두 desktop, 한 checkout에서 하나씩, 실험마다 작업 폴더를 되돌린다. 브라우저 실행은 실행마다 다른 `TEST_RUN_ID`.
|
||||
|
||||
| ID | 목적 | 변이 패치 | 명령 | env | 상한 | 기대(지금 코드가 맞다면) |
|
||||
|---|---|---|---|---|---|---|
|
||||
| E-01 | T-01 확인 | `src/presentation/styles/theme/responsive.css`에서 86~95줄(`@media (prefers-reduced-motion: reduce) { … }`)을 지운다 | `scripts/verify.sh exec -- corepack pnpm exec playwright test tests/e2e/accessibility.spec.ts -g "reduced-motion"` | `TEST_RUN_ID=r9-l3-e01` | 15분 | 세 엔진 모두 **통과**(= 거짓 통과 확인) |
|
||||
| E-02 | T-02 확인 | `tests/browser-capabilities/opfs-runtime.spec.ts:352`와 `:470`의 `if (!(await installOpfsTab(page, scope))) return;`을 `expect(await installOpfsTab(page, scope), "OPFS supported").toBe(true);`로 바꾼다 | `scripts/verify.sh exec -- corepack pnpm exec playwright test --config playwright.capabilities.config.ts tests/browser-capabilities/opfs-runtime.spec.ts` | `TEST_RUN_ID=r9-l3-e02` | 10분 | 실패하는 엔진이 있으면 그 엔진은 지금 단언 없이 통과 중이다. 엔진별 결과를 적는다 |
|
||||
| E-03 | T-03 확인 | `scripts/check-test-evidence.ts:307-311`(`wholeUiMask` 블록)을 지운다 | ① `scripts/verify.sh exec -- node scripts/run-vitest.ts run tests/unit/test-evidence-source-rules.test.ts` ② `scripts/verify.sh exec -- sh -c 'corepack pnpm check:test-evidence:fixture; echo rc=$?'` | 없음 | 5분 | ① 4건 통과, ② rc=1이고 "Test evidence failed:" 출력(= FE-GATE-029 기대도 그대로 충족). 변이가 살아남는다 |
|
||||
| E-04 | T-06 축소 확인 | `tests/e2e/old-tab-chunk-recovery.spec.ts:195`의 `...(await preloadedWith(builds.dist.a, pageSource(aManifest, PLATFORM))),` 줄을 지운다 | `scripts/verify.sh exec -- corepack pnpm exec playwright test tests/e2e/old-tab-chunk-recovery.spec.ts --repeat-each=5` | `TEST_RUN_ID=r9-l3-e04` | 25분 | 세 엔진 15/15 통과 |
|
||||
| E-05 | 게이트 연결 현재 상태 | 없음 | `scripts/verify.sh script check:ci:gating` | 없음 | 5분 | PASS(목록 밖 시험 0, stale 항목 0). 노트북에서 스크립트 경로 대조로는 377파일 모두 어떤 스크립트에 있다 |
|
||||
|
||||
## 5. 결함 아님으로 판정한 의심
|
||||
|
||||
- **W1의 "preload-use.ts가 쓰이지 않는 preload를 검사하지 않고 WebKit 추정 경고만 받아들인다"**: 템플릿에는 사실이 아니다. 미실행 preload를 `preloadunused:`로 실패시킨다(`tests/support/browser/preload-use.ts:190-202`). WebKit 문구는 앵커가 있는 정규식 하나로만 무시한다(`strict-browser-test.ts:16-24`). 변이 시험(`tests/e2e/preload-use.spec.ts:111-120`, `:247-260`)과 문구 경계 시험(`:262-296`), 판정 시험(`:302-310`)이 있다. tech-log main에는 이 파일이 없다.
|
||||
- **route를 직접 fulfill하는 시험이 preload 검사를 덮는가**: 아니다. build script를 fulfill하는 것은 `production-csp.spec.ts:30-41` 하나이고 `fulfillBuildScript`를 쓴다. 생성 기능·접근성 spec은 API origin만 가로챈다. 지연 시험은 `route.fallback()`으로 추적기에 넘긴다(`preload-use.spec.ts:192-198`). `preloadunused` 허용을 쓰는 두 spec(boot 실패, old-tab)은 route가 아니라 빌드 서버 전환으로 실패를 만든다.
|
||||
- **SW가 제어하는 문서에서 preload 검사가 빠진다**: 빠지는 것은 맞다. 이름 붙여 실패(`preload-use.ts:198-199`)하고 SW update spec만 허용한다(`service-worker-update.spec.ts:50-52`). 1105 리뷰가 결함 아님으로 판정했고, 결과 단언 시험이 더해졌다(`:302-350`, 1105/06-03 고쳐짐).
|
||||
- **boot 실패 spec이 boot graph 전체를 `preloadunused`로 허용**: 일으킨 실패(모듈 평가 중 throw)의 직접 효과이고 엔진마다 멈추는 위치가 달라 전체가 맞다(`boot-module-failure.spec.ts:47-69`).
|
||||
- **`chunk-load-error.spec.ts`의 맨 test**: 일부러 404 import를 내는 분류 시험이고 지난 리뷰들이 이유를 받아들였다. 남는 위험은 T-04에 적었다.
|
||||
- **`vi.fn()` fetcher**: 모두 "보내지 않았다"를 단언하는 감시용이다(`tests/integration/fileserver-upload.test.ts:653-661`, `http-execution-v3-auth-profile.test.ts:110-136` 등). 네트워크 동작은 MSW strict 서버(`tests/mocks/server.ts:9`)로 본다.
|
||||
- **e2e webServer가 CI 빌드 env를 물려받음**(`playwright.config.ts:36-42`): FE-GATE-008이 증거로 쓰는 job 자신의 빌드라 의도다. 사본 빌드는 `localBuildEnvironment()`를 쓴다(`tests/e2e/support/fixture-builds.ts:57`).
|
||||
- **`tests/setup.ts`의 자식 프로세스 가드** [w2-fe-2 파일]: 기본 timeout 값을 `vitest.config.ts`와 맞추는 시험이 있고(`tests/unit/child-process-timeout.test.ts:20-22`), 가드를 끄면 실패하는 시험이 있다(`:13-18`). hook 미검사는 주석과 커밋에 적힌 한계다.
|
||||
- **참조 기능 시험 삭제로 플랫폼 검사를 잃었는가(T10)**: 표본 9개 모두 대응 시험이 있다. sign-out 판정 `tests/unit/runtime-adapters-auth-profile.test.ts:364-420`, intent 비노출 `tests/unit/http-execution-v3.test.ts:426-441`, 중복 제거·retry 겹침 `tests/platform/traffic/request-deduplication.test.ts`, fan-out `tests/platform/traffic/request-fanout.test.ts`. 전수 대조는 1절 「확인 못 한 것」.
|
||||
- **위험 커버리지 행 삭제**(`config/testing/risk-coverage.json`): 지운 기능 파일의 행만 지웠다(`e3c8db48`). 기준을 낮춘 것이 아니다.
|
||||
- **새 mutation admission 시험**(`tests/component/application-mutation-admission.test.tsx:619-942`): 같은 키 유지, 거절 종류별 판정, 보내기 전 실패를 키 순서까지 단언한다. 행동이 여럿이지만 한 흐름(제출 → 재전송 → 다음 제출)의 전이를 보는 시험이라 GWT 결함이 아니다.
|
||||
- **visual 시험이 기능 영역을 가림**: 1103 결정 D3(기능 영역을 가리고 찍음)대로다.
|
||||
- **0929/12-06(Vitest 폴더의 `*.spec.ts`를 게이트 안으로 셈)·0929/12-07(예외 목록에 담당 없음)·1101/10-05·10-06·10-08**: 1106에서 「남김」 또는 결정 대기로 정해졌다. 지금 코드도 그대로다(`scripts/lib/ungated-tests.ts:18`, `:94-95`). 다시 세지 않았다.
|
||||
@@ -0,0 +1,435 @@
|
||||
# round9 L4 — UX·디자인 시스템 (렌즈 fe-ux, fe-design-system)
|
||||
|
||||
> round9 리뷰(2026-11-12, 대상 main `5250ff95`)의 영역 기록이다. 서브에이전트가 쓴 원문을 그대로 옮겼다. 바꾼 것은 이 인용 블록과, 작업 폴더 절대 경로를 `(작업 폴더)`로 줄인 것뿐이다. 발견 ID는 이 파일의 이름표(R-01 등)이고, 라운드 ID(`1112/NN-MM`)와의 대응은 [README](2026-11-round9-review.md) 15절이다.
|
||||
|
||||
|
||||
대상: `5250ff95`(tree `75cc3752`). 전체 리뷰. 읽기만 했다. repo 파일은 고치지 않았다.
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- 판정: **고칠 것 있음.** 새 발견 17건. Critical 0 · High 0 · Medium 2 · Low 15. 우선순위는 P2 8, P3 9다. 성격은 확인된 결함 15, 미검증 1(DS-04, 실험 X-02로 확인), 구조적 위험 1(DS-07)이다.
|
||||
- Medium 두 건은 둘 다 "게이트가 통과해도 보지 않는 곳"이다.
|
||||
- DS-01: 셸·페이지 템플릿·카드 CSS가 간격·층·그림자·반경 토큰을 건너뛰고 날 값을 쓴다. 그래서 토큰을 바꿔도 밀도가 바뀌지 않는다. `src/presentation/AGENTS.md`의 "토큰 밖 색·간격을 쓰지 않는다"와 PRODUCT 원칙 3을 어긴다.
|
||||
- DS-02: 갤러리를 Storybook으로 옮기면서 두 갤러리의 전체 화면 axe 검사가 사라졌다. VD-08 결정 3을 어기고, 결함 패턴 T10에 해당한다.
|
||||
- 화면 쪽 Low 가운데 사용자에게 바로 보이는 것은 둘이다.
|
||||
- UX-01: 생성 기능은 모두 `session-required`다. 그래서 로그인 전 최종 사용자에게 "이 화면은 인증 연동 지점을 확인하기 위한 보호 라우트입니다."가 보인다.
|
||||
- UX-02: 같은 키 재전송이 429·503 `RATE_LIMIT_*`로 거절되면(1106/03-01 수정이 만든 길) "입력 내용을 확인해 주세요." 제목 아래에 나온다. 409 충돌도 같다. 0925/08-01의 완료 기준 문장이 재전송 경로에서 다시 깨진다.
|
||||
- 이월: 0929/08-01은 **남음**이다. 셸 언어 선택지에 `Pseudo`·`RTL smoke`가 그대로 있다(`src/presentation/layouts/app-shell.tsx:82-87`, `src/presentation/i18n/message-contract.ts:8-13`). 새로 세지 않는다.
|
||||
|
||||
## 1. 범위
|
||||
|
||||
**읽은 경로**
|
||||
|
||||
- `src/presentation/{templates,components,forms,i18n,pages,layouts,design-system(index·primitives 전부·patterns·icons·tokens·stories 2개),styles(theme.css, theme/*.css 6개)}`
|
||||
- 상태 화면 문구 확인을 위해 `src/presentation/routes/app-router.tsx:81-310`과 `src/presentation/providers/session-provider.tsx:78-107`
|
||||
- `examples/platform-overview-page.tsx`는 import와 PageHeader 사용만 봤다. 이 화면의 위치는 결정 대기 D2다.
|
||||
- `.storybook/main.ts`, `.storybook/preview.tsx`
|
||||
- `tests/storybook/*.spec.ts`, `tests/visual/*.spec.ts`, `playwright.visual.config.ts`, `playwright.storybook.config.ts`
|
||||
- 골든 PNG는 이름과 갱신 커밋만 봤다(5장. 바뀐 3장은 `7625dc45`·`c7e80f2f`).
|
||||
- `docs/styling/design-tokens.md`, `docs/manual/02-decision-tables.md` 4·6절, `docs/manual/reference/{global-ids,patterns}.md`(필요한 절)
|
||||
- 설계서 세 개의 필요한 절: design-system-platform 1·8·9·10·11·12·13절, routing 6·7·11·12절, data-flow 7.2·8절
|
||||
- 생성 화면 템플릿: `scripts/create-feature.ts`의 `renderMessageCatalog`·`renderListPage`, `scripts/create-feature-write-slice.ts`의 `renderWriteMessages`·`renderDetailPage`·`renderCreatePage`
|
||||
- 기준과 근거: `scripts/check-design-system.ts`, `scripts/lib/design-system-rules.ts`, `scripts/check-i18n.ts`, `.dependency-cruiser.json`의 디자인 시스템 규칙, `PRODUCT.md`, ADR VD-08, `CHANGELOG.md` 알려진 제한
|
||||
- 지난 리뷰: 1106 `08-presentation.md`(이월 확인), 1101 `08-presentation.md` 휴리스틱 표, `2026-11-01-ui-design-audit.md`
|
||||
- `bbde570`과의 차이: `git diff --stat bbde570 5250ff95`로 바뀐 45파일을 먼저 봤다. 그중 `use-app-form.ts`, `catalog.ts`, `component.css`, `base.css`, `primitives.css`, `galleries.stories.tsx`, `preview.tsx`, `tests/visual/*`, `tests/storybook/galleries.spec.ts`는 줄 단위로 봤다.
|
||||
|
||||
**쓴 스킬과 그 기준으로 본 것**
|
||||
|
||||
- `fe-ux`
|
||||
- 함정 1(템플릿 선택) → UX-06
|
||||
- 함정 2(disabled 대신 pending) → UX-05
|
||||
- 함정 5·6(서버 원문, 문자열 조립) → UX-07, 5절
|
||||
- 함정 8(결과 불명 화면) → DS-03
|
||||
- 함정 11(예제와 최종 사용자 화면을 섞음) → UX-01
|
||||
- 체크리스트 "loading이 내용 모양을 따른다" → UX-04
|
||||
- 체크리스트 "날짜·숫자·목록은 formatter" → UX-03
|
||||
- 체크리스트 "409를 검증 오류로 위장하지 않는다" → UX-02
|
||||
- 체크리스트 "h1 = catalog 제목" → UX-07
|
||||
- `fe-design-system`
|
||||
- 함정 1(검사가 날 px를 안 본다) → DS-01
|
||||
- 함정 3(color-mix) → DS-08
|
||||
- 함정 7(API를 열어 둔다) → DS-07
|
||||
- 함정 10(골든 허용치) → DS-04
|
||||
- 함정 11(갤러리 story만 골든에 든다) → DS-03
|
||||
- 체크리스트 "새 component 토큰은 contract에" → DS-05
|
||||
- 체크리스트 "primitive→semantic 파생" → DS-06
|
||||
- 체크리스트 "필수 story" → DS-03
|
||||
- 체크리스트 아이콘 토큰 이름 → DS-08
|
||||
|
||||
**실행 결과(읽기만)**
|
||||
|
||||
- desktop `/tmp/claude-gates/r9fe-base/summary.txt`를 읽었다. tree `75cc3752`(HEAD tree와 같음)에서 다음이 rc=0이다.
|
||||
- FE-GATE-006(component)
|
||||
- FE-GATE-008(e2e·storybook·visual)
|
||||
- FE-GATE-010(`check:design-system`·`check:i18n`·architecture)
|
||||
- FE-GATE-011(story build)
|
||||
- FE-GATE-013은 rc=1이다(결정 D8, 이 영역 판정에 쓰지 않음).
|
||||
- 게이트 로그는 두 줄 요약이라 시험별 결과는 읽지 못했다. `snapshot/`은 아직 없다.
|
||||
- 아래 발견은 "게이트가 통과하는데 보지 않는 것"이라 이 결과와 모순되지 않는다.
|
||||
|
||||
**확인 못 한 것(화면을 띄워야 아는 것)**
|
||||
|
||||
- 다크 테마에서 modal 가림막이 밝은 색으로 깔리는지. `--dialog-backdrop`이 다크에서 밝은 `--color-content` 55%다(`component.css:168-172`).
|
||||
- 열어 볼 곳: Storybook `platform-design-system--overlay-interaction`의 dark, 또는 `/` 390px dark에서 메뉴 drawer를 연다.
|
||||
- UX-05의 포커스 유실을 세 엔진에서 실제로 보는 것.
|
||||
- 열어 볼 곳: 생성 기능의 목록 라우트를 로그인 전에 열고, "로그인 시작"을 누른 뒤 sign-in이 실패하는 경우.
|
||||
- UX-02를 생성 기능 화면에서 실제로 보는 것.
|
||||
- 열어 볼 곳: `--with-create --keyed` 작성 라우트에서 첫 저장의 응답을 잃게 하고, 재전송에 503 `RATE_LIMIT_UNAVAILABLE`을 준다.
|
||||
- en-XA·320px에서 StatusPage, ErrorSummary, 긴 FormFailureStatus의 배치. 갤러리와 골든에 없다(DS-03).
|
||||
- RTL에서 Pagination 아이콘 방향과 Switch thumb 위치. 코드에는 있다.
|
||||
|
||||
## 2. 발견
|
||||
|
||||
### UX-01 상태 화면 문구가 템플릿 개발자용이고, 행동을 말하면서 행동 버튼이 없다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함 · 24, 28, 3, 23 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low · P2 · M0(문구를 보는 검사 없음) · E1 |
|
||||
| 근거 | `src/presentation/i18n/catalog.ts`의 문구 셋이 구현 설명이다. :88-89 `route.auth.required.description` "이 화면은 인증 연동 지점을 확인하기 위한 보호 라우트입니다."(en :294-295 "…demonstrates the authentication integration seam"), :82-83 `route.auth.integration.description` "외부 인증 소유자가 연결되면…", :78-79 `route.disabledFeature.description` "…코드에는 포함되어 있으며 운영자가 다시 켤 수 있습니다."<br>`app-router.tsx:130-165`: 잘못된 주소·끈 기능 화면은 "안전한 탐색 링크를 사용해 주세요." 같은 `<p>`만 있고 `primaryAction`이 없다. 같은 템플릿의 `not-found-page.tsx:12-17`은 "홈으로 이동" 링크를 준다. `:262-271` integration-failed 화면도 행동이 없다.<br>생성 기능은 `access: "session-required"`다(`scripts/create-feature.ts:578`, `scripts/create-feature-write-slice.ts:130`). |
|
||||
| 발생 조건 | 파생 서비스에서 로그인 전 사용자가 생성 기능 라우트를 열 때. 운영자가 기능을 끄거나 주소가 틀렸을 때 |
|
||||
| 영향 | 최종 사용자가 개발용 설명을 읽는다. 끈 기능과 잘못된 주소 화면에서는 다음 행동 버튼이 없다. 이 catalog는 템플릿 소유 파일이라 제품이 고치려면 템플릿 파일을 고쳐야 한다(결함 패턴 S4). 모든 파생 서비스에 복제된다 |
|
||||
| 약속 | `PRODUCT.md` 원칙 1(디자인 시스템은 최종 사용자용, 예제는 개발자용, 섞지 않는다), fe-ux 함정 11, 체크리스트 "오류는 무엇이 틀렸고 어떻게 고치는지 쓴다", routing 설계 7.5절 "각 변형은 … 안전한 primary/secondary action" |
|
||||
| 최소 개선 방향 | 세 묶음 문구를 최종 사용자 말로 바꾼다(예: "이 화면을 보려면 로그인해 주세요.", "지금은 로그인할 수 없습니다. 잠시 후 다시 시도해 주세요."). 운영 설명은 진단으로 보낸다. `InvalidRouteSurface`·`DisabledFeatureSurface`·integration 화면에 `NotFoundPage`처럼 홈 링크 `primaryAction`을 준다 |
|
||||
| 완료 기준 | 이 키들의 ko·en 문구에 "라우트·연동 지점·seam·코드에는 포함·운영자"가 없다. 세 화면에 링크 행동이 하나씩 있다 |
|
||||
| RED 시험 | `tests/component/route-status-surfaces.test.tsx`: `invalid-route`·`disabled-feature`·`auth-integration-required` 표면에 `getByRole("link", { name: KO_MESSAGES["action.goHome"] })`가 있다. 지금 실패하고, 고치면 통과한다 |
|
||||
|
||||
### UX-02 입력과 무관한 저장 실패가 ErrorSummary "입력 내용을 확인해 주세요." 아래에 나온다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함(일부는 수정이 만든 결함, 결함 패턴 G13) · 6, 28, 24, 23 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low · P2 · M1 · E1 |
|
||||
| 근거 | `src/presentation/forms/use-app-form.ts:432-437`: 같은 키 재전송이 쓰기 전에 거절되면 `setFormErrors(["form.resendLater"])`. 1106/03-01 수정 `25685871`이 넣었다.<br>`:313-317`: 선언한 409 `CONFLICT`가 `setFormErrors(["form.conflict"])`.<br>생성 작성 페이지가 `form.formErrors`를 `ErrorSummary`에 넘긴다(`scripts/create-feature-write-slice.ts:698-705`).<br>`ErrorSummary`는 `role="alert"`이고 제목이 항상 `form.errorSummary` "입력 내용을 확인해 주세요."다(`src/presentation/forms/form-components.tsx:56-62`).<br>같은 순간 feedback 자리에는 결과 불명 `AsyncSurface`가 있다. 시험 `tests/component/form-foundation.test.tsx:1190-1196`은 `form-errors` testid의 글자만 보고, 어느 표면에 나오는지는 보지 않는다 |
|
||||
| 발생 조건 | (a) KEYED 쓰기의 응답을 잃은 뒤 "같은 요청으로 다시 보내기"가 429·503 `RATE_LIMIT_*`를 받을 때. (b) `refusedBeforeWrite`에 적고 `refusalMessages`에 적지 않은 409(`02-decision-tables.md:188`이 이 동작을 안내한다) |
|
||||
| 영향 | (a)에서는 저장 버튼이 꺼져 있는데 "입력 내용을 확인"하라고 해서 사용자가 입력을 고치려 한다. 알림도 둘(alert + status)이 함께 나온다. 0925/08-01의 완료 기준 "'입력 내용을 확인해 주세요' 제목은 나오지 않는다"(429)가 재전송 경로에서 다시 깨진다 |
|
||||
| 약속 | data-flow 설계 8절 필수 동작 5("409는 validation error로 위장하지 않음")와 5a("401·403·429 같은 입력 외 실패는 ErrorSummary가 아니라 FormFailureStatus"), `form-contracts.ts:21` 주석, fe-ux 체크리스트 |
|
||||
| 최소 개선 방향 | `formErrors`는 입력 오류만 담는다. 재전송 거절 안내는 feedback 자리로 보낸다(결과 불명 `AsyncSurface`의 설명, 또는 `FormFailureStatus`). 충돌은 `form.result === "conflict"`일 때 feedback에 충돌 문구와 행동을 둔다. 결정 D10(결과 불명과 키를 지킨다)은 그대로다. 바꾸는 것은 표면뿐이다 |
|
||||
| 완료 기준 | 두 경로에서 `form.errorSummary` 제목이 없다. 안내 문구는 feedback 자리에 있고 포커스가 그곳으로 간다 |
|
||||
| RED 시험 | `form-foundation.test.tsx` 1155행 시험의 harness가 실제 `ErrorSummary`와 `FormPage feedbackId`를 그리게 한다. 재전송 거절 뒤 `queryByRole("heading", { name: KO_MESSAGES["form.errorSummary"] })`가 `null`인지 단언한다. 409 선언 경로도 같다. 지금 실패한다 |
|
||||
|
||||
### UX-03 숫자를 locale formatter 없이 그린다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함 · 23, 1 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low · P3 · M0 · E1 |
|
||||
| 근거 | 생성 목록 문구 "총 {count}개 항목" / "Total items: {count}"에 `query.data.total`을 그대로 넣는다(`scripts/create-feature.ts:856`, `:864`, `:1203-1204`). `resolveMessage`는 `String(value)`만 한다(`message-contract.ts:115-118`).<br>`TextArea` 남은 글자 수가 en에서 단수형이 없다("1 characters remaining", `catalog.ts:365`, `text-area.tsx:66-71`).<br>`ProgressBar`가 `{Math.round(...)}%`를 글자로 붙인다(`progress-bar.tsx:13`).<br>`useLocale()`의 `number()`·`plural()`(`locale-provider.tsx:104-110`)을 쓰는 화면 코드가 0곳이다(`git grep`) |
|
||||
| 발생 조건 | 목록 항목이 1,000개 이상일 때, en에서 남은 글자가 1일 때 |
|
||||
| 영향 | "총 12345개 항목"이 되고, 영어 문법이 틀린다. 생성 뼈대라 모든 기능에 복제된다 |
|
||||
| 약속 | fe-ux 체크리스트 "날짜·숫자·목록은 locale formatter", design-system-platform 12절 국제화, 9절 plural/select |
|
||||
| 최소 개선 방향 | 생성 목록은 `{ count: number(query.data.total) }`. 이 키의 값 타입을 string으로 받게 한다. `TextArea`는 `plural`로 단수·복수를 고른다. `ProgressBar`는 `number(value / max, { style: "percent" })` |
|
||||
| 완료 기준 | 생성 목록이 1,234를 "1,234"로 보인다. en 남은 1자가 단수형이다 |
|
||||
| RED 시험 | 생성 페이지 시험(`renderPageTest`)에 total 12345 시나리오를 넣고 "총 12,345개 항목"을 기대한다. `TextArea`는 en-US, `maxLength=5`, 값 4자에서 "1 character remaining"을 기대한다. 둘 다 지금 실패한다. ProgressBar는 ko·en에서 결과가 같아 RED가 없다 |
|
||||
|
||||
### UX-04 라우트 `loadingSurface`가 로딩 모양을 고르지 않는다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함 · 22, 9, 4 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low · P3 · M0 · E1 |
|
||||
| 근거 | `app-router.tsx:81-97`: `loadingSurface`는 `data-surface` 속성으로만 쓰인다. 모든 라우트가 같은 `LoadingSurface`(블록 하나 `.ui-skeleton` h-24, `primitives.css:125-127`)를 그린다. `AsyncSurface`의 `initial-loading`도 같다(`async-surface.tsx:161`).<br>매뉴얼은 이 값을 "로딩 화면 이름"으로 정하라고 한다(`docs/manual/01-add-a-feature.md:438`). 생성 명령은 `"<base>-list"`를 넣는다(`create-feature.ts:579`) |
|
||||
| 영향 | 기능 작성자가 효과 없는 값을 정한다. 목록·상세·폼의 첫 로딩이 내용과 다른 모양이라 로딩이 끝날 때 배치가 크게 바뀐다 |
|
||||
| 약속 | fe-ux 체크리스트 "loading surface가 실제 내용 모양(collection·detail·form)을 따른다", routing 설계 6.1절, 12절 "route metadata가 loading … 행동에 실제 연결된다" |
|
||||
| 최소 개선 방향 | 권하는 안: `LoadingSurface`에 `shape: "page" \| "collection" \| "detail" \| "form"`(닫힌 union) prop을 둔다. 라우트 `loadingSurface`를 그 union으로 좁혀 `RouteLoadingSurface`가 고르게 하고, 생성 명령은 `collection`을 넣는다. 다른 안: 매뉴얼을 "진단 이름일 뿐 모양은 같다"로 고치고 렌즈 체크리스트에서 빼는 것. 이 안은 소유자 결정이 필요하다 |
|
||||
| 완료 기준 | `collection`과 `form` 로딩의 DOM 구조가 다르다. 매뉴얼 문장과 동작이 같다 |
|
||||
| RED 시험 | component 시험에서 `loadingSurface`가 다른 두 라우트의 로딩 표면이 서로 다른 skeleton 구조인지 단언한다. 지금 실패한다 |
|
||||
|
||||
### UX-05 진행 중 버튼을 `disabled`로 끄는 길이 템플릿 API에 남았다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함 · 28, 22, 23 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low · P3 · M1 · E1(포커스 유실은 미검증, fe-a11y로 넘김) |
|
||||
| 근거 | `PageActionDefinition` 버튼에는 `disabled`만 있고 `pending`이 없다(`src/presentation/templates/page-templates.tsx:18-31`, `:285-292`).<br>그래서 StatusPage의 로그인·복구 버튼은 진행 중 `disabled: pending`과 "처리 중…"으로 바뀐다(`app-router.tsx:289-297`). 셸 헤더 세션 버튼도 같다(`app-shell.tsx:95-111`).<br>`useSessionAction().run`은 진행 중 중복 실행을 막지 않고 `disabled`에 기댄다(`session-provider.tsx:92-107`) |
|
||||
| 발생 조건 | 키보드로 "로그인 시작"을 누르고 sign-in이 실패할 때 |
|
||||
| 영향 | 실패 알림(`shell.session.actionFailed`)이 뜰 때 포커스는 이미 body에 있다. 실패 뒤 다음 행동을 잃는 결함 패턴 C11이다 |
|
||||
| 약속 | fe-ux 함정 2, `docs/manual/02-decision-tables.md` 6절("꺼진 버튼은 키보드 포커스를 잃는다") |
|
||||
| 최소 개선 방향 | `PageActionDefinition` 버튼에 `pending`·`pendingLabel`을 더해 `Button`으로 넘긴다. `run`이 진행 중이면 무시하게 한다(또는 pending인 `Button`이 활성화를 삼키게 한다). 라우터와 셸이 `pending`을 쓴다 |
|
||||
| 완료 기준 | 진행 중에 버튼이 `disabled`가 아니고 `aria-busy="true"`다. 실패 뒤 포커스가 그 버튼에 있다 |
|
||||
| RED 시험 | `route-status-surfaces.test.tsx`에서 `beginSignIn`이 미해결인 동안 `expect(button).not.toBeDisabled()`와 `aria-busy` 단언. 지금 실패한다 |
|
||||
|
||||
### UX-06 홈이 페이지 템플릿과 `LinkButton`을 건너뛴다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함 · 23, 4 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low · P3 · M0 · E1 |
|
||||
| 근거 | `src/presentation/pages/home-page.tsx:50-55`: 템플릿 대신 자기 `section.ui-page`와 `PageHeader`를 쓴다. `:82-92`: `<Link className={index === 0 ? "ui-button" : "ui-button ui-button--secondary"}>`로 `LinkButton`(`link-button.tsx:25-51`, `index.ts:17-21`에서 공개)을 손으로 다시 만든다 |
|
||||
| 영향 | `PRODUCT.md`는 홈이 파생 서비스에 남는다고 적는다. 그래서 그대로 복제되고, 개발자가 따라 하는 예가 된다. `LinkButton`의 variant·size가 바뀌면 홈만 어긋난다 |
|
||||
| 약속 | fe-ux 체크리스트 "페이지는 다섯 템플릿 중 하나", brief의 "primitive를 우회한 날 스타일" |
|
||||
| 최소 개선 방향 | `StandardPage` + `LinkButton variant="primary"/"secondary"` |
|
||||
| 완료 기준 | `home-page.tsx`에 `ui-button` 문자열이 없다. `app-shell-wide-light` 골든 차이가 0이거나, 바뀌면 의도한 것이다 |
|
||||
| RED 시험 | 별도 RED 없음(리뷰 항목). 바꾼 뒤 FE-GATE-008 visual로 확인한다 |
|
||||
|
||||
### UX-07 ko·en 문구 뜻이 다르고, 오류 요약 항목을 JSX 글자로 잇는다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함 · 23, 9 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low · P3 · M3(키 일치만 `check:i18n`) · E1 |
|
||||
| 근거 | `form.conflict`: ko는 "…최신 상태를 확인해 주세요."로 행동을 말하고 en은 그 문장이 없다(`catalog.ts:153-154` 대 `:359-360`).<br>`route.NOT_FOUND.title`: en "Page not found"(문서 제목)와 h1 `page.notFound.title` "Page not found."가 다르다(`:256` 대 `:322`). ko는 같다.<br>`ErrorSummary`가 `{fieldLabels[name]}: {message}`로 번역 문장 사이에 JSX 글자 ": "를 넣는다(`form-components.tsx:75`) |
|
||||
| 약속 | fe-ux 체크리스트 "h1이 catalog 제목과 같다", "버튼·오류는 어떻게 고치는지", design-system-platform 9절 금지 "번역 문장 중간에 JSX 문자열을 연결" |
|
||||
| 최소 개선 방향 | en `form.conflict`에 "Check the latest version."을 더한다. 두 not-found 제목을 맞춘다. `form.errorSummary.item: "{label}: {message}"` 키를 둔다 |
|
||||
| 완료 기준 | 위 세 곳이 고쳐진다 |
|
||||
| RED 시험 | locale마다 `route.NOT_FOUND.title === page.notFound.title`인지 보는 unit 시험. en에서 지금 실패한다 |
|
||||
|
||||
### DS-01 스타일 파일이 간격·층·그림자·반경 토큰을 건너뛰고 날 값을 쓴다. 필수 semantic 토큰 7개는 아무 스타일도 읽지 않는다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함 · 3, 22, 23, 21, 25 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | **Medium · P2** · M1(규칙은 있고 검사는 없다: fe-design-system 함정 1) · E1 |
|
||||
| 근거 | `src/presentation/styles/theme/*.css`의 padding·margin·gap 날 값 선언이 73개다. 그중 60개는 같은 값의 `--space-*` 토큰이 있다(파일 읽기 스크립트로 셈). `shell.css`, `pages.css`, `templates.css`는 `var(--space-*)`를 한 번도 쓰지 않는다. 예: `templates.css:29` `gap: 1.25rem`, `:87` `padding: 1rem`, `:14-15` `font-size: 0.8rem; font-weight: 800`, `:128` `font-size: 1.1rem`.<br>토큰과 같은 값을 손으로 쓴 곳: `primitives.css:17`·`:161` `min-height: 2.75rem`(= `--size-control-md`), `primitives.css:375`·`shell.css:140`·`pages.css:155` `999px`(= `--radius-full`).<br>층: `shell.css:47` `z-index: 30`(= `--layer-sticky`), `responsive.css:19` `50`(= `--layer-navigation`), `templates.css:143` `10`, `shell.css:16` `100`.<br>그림자: 카드·패널이 `--elevation-panel` 대신 날 그림자를 쓴다(`primitives.css:286`, `pages.css:159`, `.ui-panel`의 Tailwind `shadow-sm`, `primitives.css:9`). dialog는 `--radius-modal` 대신 `--radius-surface`를 쓴다(`primitives.css:409`). 가림막 비율은 `--opacity-scrim: 0.55`가 있는데 `--dialog-backdrop-weight: 55%`로 다시 적었다(`component.css:167`).<br>`token-contract.ts:17-44`가 필수로 적은 semantic 토큰 가운데 `--layer-navigation`, `--layer-modal`, `--opacity-scrim`, `--opacity-skeleton`, `--elevation-panel`, `--color-disabled-content`, `--color-action-pressed`를 읽는 스타일이 0개다 |
|
||||
| 발생 조건 | 파생 서비스가 밀도·층·그림자를 토큰으로 조절할 때(PRODUCT의 업무 도구·일반 서비스·랜딩) |
|
||||
| 영향 | `--space-*`, `--layer-*`, `--opacity-scrim`, `--elevation-panel`, `--radius-modal`을 바꿔도 셸·페이지 템플릿·카드가 그대로다. UI-03의 이유 문장(`design-system-rules.ts:78-80` "규칙을 바꿔도 아무것도 바뀌지 않는다")과 같은 실패가 semantic 층에서 난다. 템플릿 소유 CSS라 모든 파생 서비스에 복제된다 |
|
||||
| 약속 | `src/presentation/AGENTS.md` "토큰 밖 색·간격을 쓰지 않는다", `docs/styling/design-tokens.md` "component는 … 간격, 글자, … 모서리 반경 토큰을 정적 class로 쓴다"와 「이름 있는 semantic 토큰을 먼저 쓴다」, `PRODUCT.md` 원칙 3 |
|
||||
| 최소 개선 방향 | (1) 날 간격·글자 크기·반경·z-index·그림자를 토큰이나 Tailwind scale로 바꾼다. 맞는 단계가 없는 값(0.45, 0.65, 0.85rem 등)은 가까운 단계로 반올림하거나 scale에 단계를 더한다. (2) 층은 `--layer-*`, 패널 그림자는 `--elevation-panel`, dialog는 `--radius-modal`, 가림막은 `--opacity-scrim`을 읽는다. (3) `check:design-system`에 두 규칙을 더한다. styles 아래 길이·z-index·box-shadow 날 값 거절(허용: `0`, `1px` 테두리, `%`), 그리고 `REQUIRED_SEMANTIC_TOKENS`에도 `unreadTokenFailures` |
|
||||
| 완료 기준 | 위 날 값 0건(허용 목록 제외). 필수 semantic 토큰마다 읽는 스타일이 있다. 골든 차이는 반올림으로 생긴 것만이고, 커밋 본문에 이유가 있다 |
|
||||
| RED 시험 | `tests/unit/design-system-rules.test.ts`에 `unreadTokenFailures(REQUIRED_SEMANTIC_TOKENS, styles)`를 더한다. 지금 7건으로 실패한다. 날 길이 규칙은 거절 fixture와 통과 fixture를 함께 둔다. 죽은 토큰 확인은 실험 X-03 |
|
||||
|
||||
### DS-02 갤러리를 story로 옮기면서 두 갤러리의 전체 화면 axe 검사를 잃었다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함(결함 패턴 T10) · 10, 21 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | **Medium · P2** · M1 · E1 |
|
||||
| 근거 | `bbde570`에서는 `/examples/ui`·`/examples/states`가 등록 라우트였다(`platform-examples-contract.ts:15-40`). 그래서 `tests/e2e/accessibility.spec.ts`의 라우트 순회가 두 화면 전체에 axe를 돌렸다.<br>지금은 다음뿐이다. `tests/storybook/galleries.spec.ts:58-72`는 열린 대화 상자(`.include(".ui-dialog")`)만 본다. `workshop.spec.ts:8-28`은 overlay story 하나만 본다. ScreenStates story와 DesignSystem story 전체, `Primitives`·`LongPseudoLikeContent` story는 어느 시험도 axe를 돌리지 않는다.<br>옮긴 커밋 `c7e80f2f` 본문의 옮긴 목록에도 전체 화면 axe가 없다.<br>`.storybook/preview.tsx:118-119` `a11y.test: "error"`는 이것을 돌릴 runner(addon-vitest, test-runner)가 `package.json`에 없어 효과가 없다. 시험은 `a11y.manual:!true`로 addon도 끈다 |
|
||||
| 발생 조건 | 상태 화면(로딩·빈·오류·인증·권한·없음)이나 갤러리 primitive에 critical·serious axe 위반이 생길 때 |
|
||||
| 영향 | merge 게이트가 그 위반을 통과시킨다. 템플릿은 기능이 0개라 accessibility.spec이 보는 라우트는 셋(APP_HOME, EXAMPLES_PLATFORM, NOT_FOUND)뿐이다. 그래서 `EmptySurface`·`TerminalErrorSurface`·`AuthRequiredSurface`·`ForbiddenSurface`는 템플릿 상태에서 axe를 전혀 받지 않는다 |
|
||||
| 약속 | ADR VD-08 결정 3 "interaction과 story-level axe는 Playwright가 정적 Storybook을 대상으로 실행한다", design-system-platform 10.1 "a11y 결과를 CI에서 error로 처리" |
|
||||
| 최소 개선 방향 | `tests/storybook`에 axe 시험을 더한다. 모든 story(또는 최소 갤러리 둘과 DS story 셋)를 light·dark에서 열고 WCAG 태그 critical·serious 0을 단언한다. 효과 없는 `a11y.test`는 지우거나 실제 runner와 잇는다 |
|
||||
| 완료 기준 | 위 story 전부에 axe가 돈다. 위반을 넣는 변이가 `test:storybook`에서 실패한다 |
|
||||
| RED 시험 | 실험 X-01의 probe가 지금 위반을 보고하는지 본다. 고친 뒤에는 `TerminalErrorSurface`의 `aria-labelledby`를 없는 id로 바꾸는 변이가 새 시험에서 실패해야 한다 |
|
||||
| 넘김 | 위반 내용 판정은 fe-a11y |
|
||||
|
||||
### DS-03 공개 배럴 컴포넌트 상당수에 story가 없고, 결과 불명 화면은 갤러리·골든에 없다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함 · 10, 21, 20 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low · P2 · M0 · E1 |
|
||||
| 근거 | `src/presentation/design-system/index.ts`의 값 export 71개 가운데 story 파일에 나오는 것은 26개다.<br>story가 없는 것:<br>- primitive: `SearchField`, `ConfirmationDialog`, `Drawer`, `Popover`, `Breadcrumbs`, `Pagination`, `LinkButton`, `Separator`, `IconButton`(단독)<br>- pattern: `DataTable`, `DisclosureGroup`, `PaginationBar`, `SearchFilterToolbar`, `AccessSurface`<br>- 템플릿 다섯: `StandardPage`, `CollectionPage`, `DetailPage`, `FormPage`, `StatusPage`<br>- 폼: `ErrorSummary`, `FormFailureStatus`, `DirtyNavigationDialog`, `FormActions`<br>- 아이콘 9개<br>`AsyncSurface`는 refreshing만 있다(`galleries.stories.tsx:363-389`). 결과 불명(확인·같은 요청 다시 보내기), 충돌, stale, 저장 중이 없다.<br>있는 story도 variant 하나씩이다(`design-system.stories.tsx:31-68`). theme·locale toolbar가 없다(`preview.tsx`에 `globalTypes` 없음, `platform.visual.spec.ts:96-97` 주석) |
|
||||
| 영향 | fe-ux 함정 8의 핵심 화면(결과 불명), 페이지 템플릿, 폼 오류 요약의 배치 회귀를 골든과 story가 잡지 못한다. 파생 서비스가 쓸 컴포넌트의 상태 행렬을 볼 곳이 없다 |
|
||||
| 약속 | fe-design-system 체크리스트 "필수 story가 있다: default, 모든 variant, disabled·readonly, pending, 오류, 긴 문구, 빈 값, light·dark, compact, 키보드", 함정 11, design-system-platform 10.2·13절("story 없이 runtime gallery 하나로 모든 variant를 대표" 금지) |
|
||||
| 최소 개선 방향 | 1단계: ScreenStates 갤러리에 결과 불명(재전송 가능)·충돌·stale·StatusPage·FormFailureStatus·ErrorSummary를 더하고 `state-surfaces-light` 골든을 갱신한다(이유는 본문에). 2단계: overlay·form primitive부터 CSF story(variant·disabled·pending·error·긴 문구)를 쓴다. 3단계: theme·locale `globalTypes` decorator |
|
||||
| 완료 기준 | 화면 컴포넌트 export마다 story가 하나 이상 있다(시험이 대조). 결과 불명 surface가 골든에 든다 |
|
||||
| RED 시험 | unit 시험: `index.ts`의 PascalCase 값 export가 어느 `*.stories.tsx`에 나오는지 대조한다(허용 목록: `Portal`, `FocusRing`, `VisuallyHidden`, hook). 지금 30개 이상으로 실패한다 |
|
||||
|
||||
### DS-04 시각 골든의 색 허용치(기본 threshold 0.2)가 토큰 색 변경을 통과시킨다. 알려진 제한으로만 적혀 있다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 미검증(작성자 실험 주장, E0 → 실험 X-02) · 21, 10 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low · P2 · M3(픽셀 수만) · E0 |
|
||||
| 근거 | `playwright.visual.config.ts:41-51`는 `maxDiffPixels: 50`만 정하고 `threshold`를 두지 않는다(Playwright 기본값 0.2).<br>`CHANGELOG.md:148` 알려진 제한에 적혀 있다. 커밋 `c7e80f2f` 본문에 따르면 어두운 `--color-danger` red-500→600과 밝은 `--color-danger-surface` 색상각 25→145가 옛 골든과 새 골든을 모두 통과했다 |
|
||||
| 영향 | 위험 표면이 초록빛으로 바뀌어도 골든이 통과한다 |
|
||||
| 약속 | VD-08 결정 8 "실제 … theme 또는 상태 변화가 숨겨지도록 … 하지 않는다", fe-design-system 함정 10, 소유자 프로그램의 "기록만 하지 않고 고친다" |
|
||||
| 최소 개선 방향 | `toHaveScreenshot`에 더 작은 `threshold`(0.05 정도)를 둔다. 기준을 **올리는** 쪽이라 꼭 지킬 것 4에 걸리지 않는다. 글꼴이 고정된 깨끗한 빌드는 0 px 차이라는 기존 주장(`playwright.visual.config.ts:45-47`)을 반복 실행으로 확인한다 |
|
||||
| 완료 기준 | 위 두 변이가 `test:visual`에서 실패하고, 변이 없이는 3회 모두 통과한다 |
|
||||
| RED 시험 | X-02 |
|
||||
|
||||
### DS-05 1106/08-03이 더한 component 토큰 셋이 `token-contract.ts`에 없어 UI-03 검사 밖이다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함 · 21, 23 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low · P3 · M3(목록에 있는 것만) · E1 |
|
||||
| 근거 | `component.css:167-177`의 `--dialog-backdrop-weight`, `--dialog-backdrop`, `--dialog-backdrop-on-surface`가 `REQUIRED_COMPONENT_TOKENS`(`token-contract.ts:46-56`)에 없다.<br>검사는 그 목록만 본다(`check-design-system.ts:102-105`). 그런데 문서는 "UI-03: 모든 component 토큰은 어떤 스타일이든 하나에서 읽힌다"라고 적는다(`design-tokens.md:24`) |
|
||||
| 영향 | 목록에 없는 component 토큰은 읽히지 않아도 게이트가 모른다. 문서 문장보다 검사가 좁다 |
|
||||
| 약속 | fe-design-system 체크리스트 "새 component 토큰은 `token-contract.ts`에 이름이 있고 어떤 스타일이 읽는다 — UI-03" |
|
||||
| 최소 개선 방향 | 세 토큰을 contract에 더한다. `--dialog-backdrop-weight`는 DS-01과 함께 semantic `--opacity-scrim`으로 대신한다(`calc(var(--opacity-scrim) * 100%)`). 검사가 `component.css`에 정의된 이름 전부를 contract와 대조하게 한다 |
|
||||
| 완료 기준 | `component.css`의 정의와 contract 목록이 같고, 그 대조를 시험이 한다 |
|
||||
| RED 시험 | unit 시험: `component.css`의 `--x:` 정의 ⊆ `REQUIRED_COMPONENT_TOKENS`. 지금 3건으로 실패한다 |
|
||||
|
||||
### DS-06 `semantic.css`가 팔레트를 거치지 않은 날 `oklch()` 36개를 정의한다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함(문서와 코드가 다름) · 3, 23, 9 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low · P3 · M0 · E1 |
|
||||
| 근거 | 밝은 테마 13개(`semantic.css:82`, `:85-96`: focus, info·success·warning·danger의 content·surface·border), 어두운 테마 23개(`:124-152`). `PRODUCT.md:31` "토큰은 primitive → semantic → component 세 단계로 파생된다", `design-tokens.md:3-7` "`primitive.css`에는 … 팔레트 … `semantic.css`는 그것을 역할에 연결" |
|
||||
| 영향 | 팔레트만 바꿔 리브랜드하면 status 색, focus, 다크 테마 대부분이 그대로다 |
|
||||
| 약속 | 위 두 문장, fe-design-system 체크리스트 "새 값은 primitive → semantic → component 순서로 파생" |
|
||||
| 최소 개선 방향 | 권하는 안: status 색조(green·amber·info)와 다크 단계를 `primitive.css` 팔레트로 옮기고 semantic이 참조한다. UI-01 계산은 var 사슬을 따라가므로(`oklch-contrast.ts:53`) 막히지 않는다. 다른 안: 문서를 "semantic은 역할 전용 값을 가질 수 있다(목록)"로 고친다 |
|
||||
| 완료 기준 | semantic 값이 `var()`·`color-mix()`·키워드뿐이거나, 문서가 예외 목록을 적는다 |
|
||||
| RED 시험 | unit 시험: `semantic.css` 선언값에 `oklch(` 0건. 지금 36건으로 실패한다 |
|
||||
|
||||
### DS-07 primitive의 `className`·`style`이 범위 없이 열려 있다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 구조적 위험 · 22, 21 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low · P3 · M0 · E1 |
|
||||
| 근거 | `Button`은 `ButtonHTMLAttributes` 전체(`style` 포함)와 `className`을 그대로 넘긴다(`button.tsx:8-14`, `:42-48`). `TextField`(`text-field.tsx:5-14`, `:40`), `LinkButton`(`link-button.tsx:15-23`), `IconButton`, `Card`(`card.tsx:9`), `Dialog`(`dialog.tsx:21`)도 같다.<br>`check:design-system`은 TS에서 `#hex`·`oklch(`·`rgb(`만 찾는다(fe-design-system 함정 1). 그래서 `style={{ color: "red", padding: 13 }}`은 게이트를 지난다. 범위를 적은 문서가 없다(`git grep className -- docs/styling docs/manual` 0건) |
|
||||
| 영향 | 기능 화면이 primitive 위에 날 색·간격을 얹어도 막는 것이 없다 |
|
||||
| 약속 | fe-design-system 함정 7 "범위 없는 `className`", design-system-platform 11절 4단계 "`className` escape hatch의 범위를 정한다" |
|
||||
| 최소 개선 방향 | 공개 props에서 `style`을 뺀다(`Omit<…, "style">`). `className`은 "배치용(그리드 위치·여백)만"이라고 JSDoc과 `design-tokens.md`에 적는다 |
|
||||
| 완료 기준 | `<Button style={…} />`가 타입 오류다. 범위 문장이 있다 |
|
||||
| RED 시험 | `check:types` fixture에 `<Button style={{ color: "red" }} />`를 넣는다. 지금은 오류가 없어 fixture가 "거절되지 않음"으로 실패한다 |
|
||||
|
||||
### DS-08 fe-design-system 스킬의 기준 문장 두 곳이 실제 규칙·토큰과 다르다(범위 경로 밖, 렌즈 자체)
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함 · 9, 23, 4 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low · P3 · M0 · E1 |
|
||||
| 근거 | (1) `.claude/skills/fe-design-system/SKILL.md:35` "`color-mix()`는 `in oklab`만 쓴다". 실제 규칙은 색상각 공간(oklch·lch·hsl·hwb)만 거절한다(`design-system-rules.ts:62-71`, `design-tokens.md:23-24`). 코드는 `in srgb`를 일부러 쓴다(`component.css:173-177`. 브라우저가 반투명 색을 sRGB에서 겹쳐 그리는 것과 맞추려는 것). (2) `SKILL.md:53` "`--icon-size-*`·`--icon-stroke-*`". 실제 토큰은 `--size-icon-sm\|md\|lg`, `--icon-stroke-default`다(`primitive.css:56-59`) |
|
||||
| 영향 | 스킬을 따르는 리뷰어나 수정자가 srgb를 oklab으로 "고치면" 스크롤바 자리 색 맞춤(`scrollbar-gutter.visual.spec.ts`)이 깨진다. 없는 `--icon-size-*` 토큰을 새로 만들어 중복이 생긴다 |
|
||||
| 최소 개선 방향 | 스킬 문장을 규칙에 맞춘다: "색상각 공간 금지, 기본 oklab, 반투명 합성을 재현할 때만 srgb", "`--size-icon-*`·`--icon-stroke-default`" |
|
||||
| 완료 기준 | 두 문장이 규칙·토큰과 같다 |
|
||||
| RED 시험 | `scripts/tests/test_claude_setup.py`에 "스킬의 백틱 `--토큰` 이름은 토큰 CSS에 있다" 대조를 더한다. `--icon-size-*`로 지금 실패한다 |
|
||||
|
||||
### DS-09 `docs/styling/design-tokens.md` 「들어 있는 primitive」가 지금 primitive의 일부만 적는다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함(문서가 낡음, 결함 패턴 W1·S1) · 9, 23 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low · P3 · M0 · E1 |
|
||||
| 근거 | `design-tokens.md:47-57`은 Button·TextField·Card·Alert/Badge·Dialog·상태 표면만 적는다. 실제로는 primitive 25개, pattern 5개, 템플릿, 폼이 있다(`index.ts:4-133`). 문서는 스스로 "지금 구현된 토큰과 primitive 기준선을 적는다"고 한다(`:69`) |
|
||||
| 최소 개선 방향 | 손으로 쓴 목록을 지우고 `index.ts`와 갤러리 story를 가리킨다 |
|
||||
| 완료 기준 | 문서가 목록을 손으로 들지 않거나, 시험이 대조한다 |
|
||||
| RED 시험 | 별도 RED 없음(문서. `verify:documentation` 대상) |
|
||||
|
||||
### DS-10 지운 compact 사이드바의 CSS가 남았다. 두 번째 가림막(35%)과 날 z-index 50·40이 있다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함(죽은 사본) · 9, 23 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low · P3 · M0 · E1 |
|
||||
| 근거 | `responsive.css:17-42`의 `.app-shell__sidebar` 고정 배치, `[data-open="true"]`, `.app-shell__scrim`, 그리고 `pages.css:219-221`. `data-open`을 세우거나 `app-shell__scrim` class를 쓰는 TS·TSX는 0곳이다. compact 내비게이션은 `Drawer`다(`app-shell.tsx:126-144`) |
|
||||
| 영향 | 리브랜드할 때 가림막 정의가 둘로 보인다(dialog 55% 토큰, 죽은 35% 날 값) |
|
||||
| 최소 개선 방향 | 죽은 규칙을 지운다. compact의 `.app-shell__sidebar { display: none }`만 남긴다 |
|
||||
| 완료 기준 | 두 class 규칙이 없다. compact 골든 차이가 0이다 |
|
||||
| RED 시험 | 별도 RED 없음. 원하면 "styles의 class 선택자는 TS·TSX 어딘가에 쓰인다(실행 중 조립하는 modifier는 허용 목록)" 시험. 지금 `app-shell__scrim`으로 실패한다 |
|
||||
|
||||
## 3. 넘길 것
|
||||
|
||||
- **fe-a11y**
|
||||
- UX-05: 진행 중 `disabled`가 된 로그인 버튼의 포커스 유실을 세 엔진에서 본다. jsdom은 포커스를 떨어뜨리지 않는다.
|
||||
- DS-02: X-01이 낸 gallery axe 위반을 판정한다.
|
||||
- `DisclosureGroup`의 제목이 h2로 고정이다(`common-patterns.tsx:120`). 다른 표면은 `headingLevel` 계약(08-05)을 받는다.
|
||||
- 역할 없는 `div`에 `aria-label`이 있다(`home-page.tsx:56`).
|
||||
- dialog 닫기·alert 닫기 버튼이 2rem이다(`primitives.css:346-365`). 목표 44px(design-system-platform 8.1 "목표로 한다")에 못 미친다. AA 24px는 넘는다.
|
||||
- **fe-structure**
|
||||
- `page-templates.tsx:5-8`이 index가 공개하는 `LinkButton`을 하위 경로로 import한다. `.dependency-cruiser.json:73-77`의 예외는 파일 전체를 열지만 주석은 `PaginationLandmarkContext`만 이유로 든다(결함 패턴 S5).
|
||||
- VD-05 롤백용 `components/ui/*.ts`를 새 presentation 코드가 기본 경로로 쓴다(`async-surface.tsx:13`, `state-surfaces.tsx:2`, `form-components.tsx:6`, `use-dirty-navigation-guard.tsx:4-5`, `page-templates.tsx:4`). 제거 조건이 없다(1101 관찰과 같음).
|
||||
- `design-system/patterns/common-patterns.tsx:3-8`이 `components/state-surfaces.tsx`를 import한다. `components`는 다시 디자인 시스템을 import한다. 두 폴더가 서로를 import한다.
|
||||
- **fe-react**: 이월 1103/03-01 폼 쪽(Medium·P2)은 데이터 흐름이라 다시 판정하지 않았다.
|
||||
- **총괄**: 0929/08-01을 다시 봤다. 바뀌지 않았고 **남음**이다(셸 언어 목록에 Pseudo·RTL smoke, `app-shell.tsx:82-87`).
|
||||
|
||||
## 4. 실험 요청
|
||||
|
||||
모두 desktop의 깨끗한 checkout에서 돌린다. 실험마다 작업 폴더를 되돌린다(O-11).
|
||||
|
||||
### X-01 — DS-02: gallery·DS story의 전체 화면 axe probe
|
||||
|
||||
- 명령: `scripts/verify.sh exec -- corepack pnpm exec playwright test -c playwright.storybook.config.ts tests/storybook/zz-probe-axe.spec.ts`
|
||||
- env: 기본(CI env 불필요)
|
||||
- 상한: 15분
|
||||
- 기대: 지금 위반이 0이면 DS-02는 "통제 공백"으로만 남는다. 위반이 있으면 목록을 fe-a11y로 넘긴다.
|
||||
- 패치(새 파일, 끝나면 지운다):
|
||||
|
||||
```diff
|
||||
--- /dev/null
|
||||
+++ b/tests/storybook/zz-probe-axe.spec.ts
|
||||
@@
|
||||
+import AxeBuilder from "@axe-core/playwright";
|
||||
+import { expect, test } from "../support/browser/strict-browser-test.ts";
|
||||
+const STORIES = [
|
||||
+ "platform-galleries--design-system",
|
||||
+ "platform-galleries--screen-states",
|
||||
+ "platform-design-system--primitives",
|
||||
+ "platform-design-system--long-pseudo-like-content",
|
||||
+] as const;
|
||||
+for (const colorScheme of ["light", "dark"] as const) {
|
||||
+ for (const id of STORIES) {
|
||||
+ test(`probe axe ${id} ${colorScheme}`, async ({ page }) => {
|
||||
+ await page.emulateMedia({ colorScheme });
|
||||
+ await page.goto(`/iframe.html?id=${id}&viewMode=story&globals=a11y.manual:!true`);
|
||||
+ await expect(page.locator("#storybook-root > *").first()).toBeVisible();
|
||||
+ const { violations } = await new AxeBuilder({ page })
|
||||
+ .withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"]).analyze();
|
||||
+ console.log(id, colorScheme, JSON.stringify(violations.map((v) => [v.id, v.impact, v.nodes.length])));
|
||||
+ expect(violations.filter((v) => ["critical", "serious"].includes(v.impact ?? ""))).toEqual([]);
|
||||
+ });
|
||||
+ }
|
||||
+}
|
||||
```
|
||||
|
||||
### X-02 — DS-04: 색 허용치 구멍 확인과 고친 값 확인
|
||||
|
||||
- 명령: `scripts/verify.sh script test:visual`을 세 번 돌린다.
|
||||
- 상한: 25분
|
||||
- 1단계 변이(기대: **PASS** = 구멍 확인):
|
||||
|
||||
```diff
|
||||
--- a/src/presentation/design-system/tokens/semantic.css
|
||||
+++ b/src/presentation/design-system/tokens/semantic.css
|
||||
@@ -95 +95 @@
|
||||
- --color-danger-surface: oklch(0.96 0.035 25);
|
||||
+ --color-danger-surface: oklch(0.96 0.035 145);
|
||||
```
|
||||
|
||||
- 2단계: 1단계 변이에 아래를 더한다(기대: `state-surfaces-light` **FAIL**).
|
||||
|
||||
```diff
|
||||
--- a/playwright.visual.config.ts
|
||||
+++ b/playwright.visual.config.ts
|
||||
@@
|
||||
maxDiffPixels: 50,
|
||||
+ threshold: 0.05,
|
||||
scale: "css",
|
||||
```
|
||||
|
||||
- 3단계: semantic 변이를 되돌리고 2단계 설정만 남겨 두 번 돌린다(기대: 둘 다 PASS, 깨끗한 빌드는 0 px).
|
||||
|
||||
### X-03 — DS-01: 필수 semantic 토큰이 죽은 손잡이인지 확인
|
||||
|
||||
- 명령: `scripts/verify.sh script test:visual`
|
||||
- 상한: 15분
|
||||
- 기대: PASS. 골든 5장이 하나도 바뀌지 않으면 이 토큰을 바꿔도 화면이 안 바뀐다는 뜻이다.
|
||||
- 변이:
|
||||
|
||||
```diff
|
||||
--- a/src/presentation/design-system/tokens/semantic.css
|
||||
+++ b/src/presentation/design-system/tokens/semantic.css
|
||||
@@
|
||||
- --elevation-panel: var(--shadow-panel);
|
||||
+ --elevation-panel: 0 0 0 0.5rem red;
|
||||
@@
|
||||
- --layer-navigation: 50;
|
||||
+ --layer-navigation: -1;
|
||||
@@
|
||||
- --opacity-scrim: 0.55;
|
||||
+ --opacity-scrim: 0;
|
||||
@@
|
||||
- --radius-modal: var(--radius-md);
|
||||
+ --radius-modal: 3rem;
|
||||
```
|
||||
|
||||
### X-04 — UX-02: 재전송 거절이 어느 표면에 나오는지 component probe
|
||||
|
||||
- 명령: `scripts/verify.sh exec -- node scripts/run-vitest.ts run tests/component/zz-probe-resend-surface.test.tsx`
|
||||
- 상한: 10분
|
||||
- 기대: 지금 heading "입력 내용을 확인해 주세요."가 **보인다**.
|
||||
- 내용: `form-foundation.test.tsx` 1155행 시험의 `CoordinatedForm`을 그대로 쓰되, `form.formErrors`를 실제 `ErrorSummary`에 넘겨 그린다. 재전송 503 `RATE_LIMIT_UNAVAILABLE` 뒤 `screen.queryByRole("heading", { name: KO_MESSAGES["form.errorSummary"] })`를 출력한다. 같은 harness로 `refusedBeforeWrite`에 적은 409 경로도 출력한다.
|
||||
|
||||
## 5. 결함 아님으로 판정한 의심
|
||||
|
||||
- `component.css:173` `color-mix(in srgb, …)`: UI-02는 색상각 공간만 금지한다. sRGB는 브라우저가 겹쳐 그리는 방식을 재현하려고 일부러 쓴 것이다. 스킬 문장 쪽 문제는 DS-08로 셌다.
|
||||
- 상태 화면 eyebrow "401 · 인증 필요": 상태 코드를 금지하는 repo 규칙이 없다. 제목과 설명이 행동을 말한다(1101 휴리스틱 관찰과 같은 것).
|
||||
- 쓰지 않는 primitive 토큰(breakpoint, font-size-xs 등): 확장 지점이다. 필수인데 날 값으로 건너뛴 것만 DS-01로 셌다.
|
||||
- `components/ui/*.ts` facade: `.dependency-cruiser.json`의 주석으로 정한 VD-05 롤백이다. 쓰임새 문제는 fe-structure로 넘겼다.
|
||||
- 플랫폼 구성 화면과 갤러리 story의 한국어 고정 문구, 그리고 ESLint 범위 밖인 것: 의도다(08-07, `check-i18n.ts:62-63` 주석). 화면의 위치는 결정 대기 D2다.
|
||||
- 골든의 light/dark·compact/wide: 합쳐서 둘 다 있어 체크리스트를 충족한다. 상태 화면에 dark 골든이 없는 것은 DS-03의 1단계에서 함께 볼 개선이다.
|
||||
- compact 골든 아래쪽 오른쪽 15px의 어두운 띠: `7625dc45` 본문이 fullPage와 `--hide-scrollbars`가 만든 산물이라고 적고 받아들였다.
|
||||
- `scrollbar-gutter` header 띠: design-system-platform 8.2절에 받아들인 모습으로 적혀 있다.
|
||||
- 기능 catalog가 플랫폼 키를 덮을 수 있음: 생성 명령이 이미 있는 키를 거절한다(`create-feature.ts:279-290`). 손으로 더할 때는 접두어 규칙(`global-ids.md`)이 있다. 지원 경로에서 재현되지 않는다.
|
||||
- StatusPage `offline`·`maintenance` variant를 쓰는 곳이 없음: 확장 지점이다.
|
||||
- 생성 상세 페이지의 404 표면에 버튼이 없음: breadcrumb가 목록으로 돌아가는 길을 준다.
|
||||
- `TerminalErrorSurface`가 `onAction`이 없으면 버튼을 그리지 않음: 지원 참조는 남는다. 템플릿은 retry를 잇는다.
|
||||
- `Button`의 `pending`이 클릭을 삼키지 않음: 폼은 `pendingRef`로 중복 제출을 막는다(`use-app-form.ts:399`, `:423`). 폼 밖의 경우는 UX-05의 개선 방향에 넣었다.
|
||||
- `PageHeader`가 제목이 바뀔 때 포커스를 다시 잡는 문제: `routeOwnsFocus` 조건이 막는다(`page-header.tsx:28-33`).
|
||||
- `--dialog-backdrop-on-surface`의 색이 실제와 맞는지: `scrollbar-gutter.visual.spec.ts`가 픽셀로 보고, FE-GATE-008이 rc=0이다(desktop r9fe-base).
|
||||
- 읽은 코드·문서 안에 리뷰어에게 하는 지시는 없었다.
|
||||
@@ -0,0 +1,460 @@
|
||||
# round9 L5 — 접근성(fe-a11y) 전체 리뷰
|
||||
|
||||
> round9 리뷰(2026-11-12, 대상 main `5250ff95`)의 영역 기록이다. 서브에이전트가 쓴 원문을 그대로 옮겼다. 바꾼 것은 이 인용 블록과, 작업 폴더 절대 경로를 `(작업 폴더)`로 줄인 것뿐이다. 발견 ID는 이 파일의 이름표(R-01 등)이고, 라운드 ID(`1112/NN-MM`)와의 대응은 [README](2026-11-round9-review.md) 15절이다.
|
||||
|
||||
|
||||
대상: `5250ff95`(tree `75cc3752`). 읽기만 했다. repo 파일은 고치지 않았다.
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- 판정: **고칠 것 있음.** 새 High 0, Critical 0. Medium 1, Low 17이다(그중 `[w2-fe-2 파일]` 1).
|
||||
- Medium 하나는 수동 접근성 release 게이트 FE-GATE-028이다. 지난 release에 서명한 기록 세트를 새 release 후보에서도 통과시킨다. 기록끼리 Release ID가 같은지만 보고, 후보와 같은지는 보지 않는다(A11Y-01).
|
||||
- 템플릿 셸이 그리는 경로에서 확인한 결함은 셋이다.
|
||||
- 라우트 heading의 focus 표시를 키보드 사용자에게서도 지운다(A11Y-02). 그래서 M2를 모든 라우트에서 통과할 수 없다.
|
||||
- 셸의 세션 버튼과 로그인 안내 버튼이 처리 중에 `disabled`로 바뀌어 키보드 focus를 잃는다(A11Y-03).
|
||||
- 셸에 모든 라우트에서 열리는 modal drawer가 있는데, 라우트 기록 셋이 M4를 "modal 없음"으로 미리 채워 두었다(A11Y-07).
|
||||
- 시험 쪽 결함은 넷이다.
|
||||
- 예제 화면을 Storybook으로 옮기면서 갤러리 전체의 axe 검사가 빠졌다(A11Y-04).
|
||||
- WCAG 2.2에서 새로 생긴 AA 기준은 자동 검사도 수동 checklist도 보지 않는다(A11Y-05).
|
||||
- reduced-motion e2e는 항상 통과한다(A11Y-08).
|
||||
- 공개 라우트는 Suspense가 다 풀리기 전에 검사될 수 있다(A11Y-16, 미검증).
|
||||
- 공통 primitive 결함은 Tooltip hoverable(1.4.13 AA, A11Y-06)·Popover 이름·Menu Tab·중첩 Escape·required 표시·Toast 닫기 focus·TextArea 글자 수 발표다. 지금 템플릿 라우트에는 이 primitive를 쓰는 곳이 없다. 다운스트림이 그대로 받는다.
|
||||
|
||||
## 1. 범위
|
||||
|
||||
- 렌즈: `.claude/skills/fe-a11y/SKILL.md`(함정 1~11과 「실패는 이렇게 보인다」 전 항목). 그 기준으로 본 것:
|
||||
- 의미·이름: native element, accessible name, landmark·h1
|
||||
- 키보드·포커스: 순서, 표시, route focus, modal trap·복원, 가림
|
||||
- live region 중복
|
||||
- 폼: 오류 연결, required, 제출 실패 focus
|
||||
- 시각: 색만 쓰는지, reduced-motion, forced-colors, target 크기
|
||||
- 수동 기록과 검사기가 checklist 약속을 실제로 강제하는지
|
||||
- 함께 읽은 기준 문서:
|
||||
- `docs/work/reference/review-criteria.md` 2·3·5·8절
|
||||
- `docs/work/reference/decisions.md`, `docs/work/reference/defect-patterns.md`
|
||||
- `docs/accessibility/manual-checklist.md`, `PRODUCT.md` 「Accessibility & Inclusion」
|
||||
- `docs/design/2026-07-26-design-system-platform-design.md` 5·6·8절
|
||||
- `docs/design/2026-07-26-routing-pages-and-patterns-design.md` 6.3·11절
|
||||
- `docs/manual/02-decision-tables.md` 6절
|
||||
- 읽은 코드(현재 커밋 전체):
|
||||
- `src/presentation/design-system/**`: primitive 31개, patterns, icons, tokens, 두 stories 파일
|
||||
- `src/presentation/{components,templates,forms,layouts,pages,examples,boundaries}/**`
|
||||
- `src/presentation/routes/app-router.tsx`의 focus·title·보호 라우트 부분
|
||||
- `src/presentation/styles/theme/*.css`
|
||||
- `docs/accessibility/**`
|
||||
- 시험: `tests/e2e/accessibility.spec.ts`, `theme.spec.ts`, `app-shell.spec.ts`, `generated-feature.spec.ts`(관련 부분)
|
||||
- 시험: `tests/storybook/*.spec.ts`
|
||||
- 시험: `tests/component/{page-header-focus,layout-landmarks,ui-primitives,design-system-platform,route-status-surfaces,form-foundation}.test.tsx`(관련 부분)
|
||||
- 스크립트: `scripts/{verify-a11y-manual,write-a11y-report}.ts`, `scripts/lib/{manual-a11y-evidence,a11y-data-state}.ts`
|
||||
- 생성기: `scripts/create-feature-write-slice.ts`의 폼·상세 템플릿, `scripts/create-feature.ts`의 목록·기록 템플릿
|
||||
- 설정: `.storybook/preview.tsx`, `config/ci/gates.json`의 FE-GATE-006·008·009·028
|
||||
- `bbde570` 뒤에 바뀐 곳을 먼저 봤다.
|
||||
- 예제 화면과 참조 기능을 지웠다(`e3c8db48`).
|
||||
- 갤러리를 Storybook으로 옮겼다(`c7e80f2f`).
|
||||
- 기록을 `docs/accessibility/route-reviews/`로 옮겼다(`79dc945a`).
|
||||
- `use-app-form.ts`, CSS 세 파일도 바뀌었다.
|
||||
- 게이트 결과(desktop `/tmp/claude-gates/r9fe-base/summary.txt`, tree 일치, 읽기만):
|
||||
- FE-GATE-001~012 rc=0. FE-GATE-013 rc=1은 결정 D8로 판정에서 뺀다.
|
||||
- FE-GATE-020은 읽은 시점에 아직 돌고 있었다.
|
||||
- 게이트 로그는 한 줄 PASS뿐이고 `snapshot/`이 없었다. 그래서 `artifacts/tests/a11y.json`과 playwright 보고서는 읽지 못했다.
|
||||
- 이 리뷰의 발견은 모두 코드 판독이다(E1).
|
||||
- 확인 못 한 것(화면을 띄워야 안다. `verify-app`으로 볼 라우트·상태):
|
||||
1. 2.4.11 포커스 가림 — 생성 기능 작성 폼(`create:feature --with-create`). 필드를 8개 이상으로 늘리고 375×600에서 Tab으로 내려간다. focus된 필드가 아래에 붙은 `.form-actions--sticky`(`templates.css:141-147`)에 완전히 가려지는지 본다. `scroll-padding-bottom`이 없다. header 쪽은 `shell.css:31-33`가 처리한다.
|
||||
2. 2.4.11 포커스 가림 — gallery story(`platform-galleries--design-system`). toast를 띄운 채 오른쪽 아래 요소로 Tab할 때 `.ui-toast-region`(fixed)이 focus를 가리는지 본다.
|
||||
3. forced-colors — 같은 story. `Pagination`의 현재 페이지(`aria-current`, primary 배경, `border: 0`)와 `Tabs`의 선택 표시가 남는지 본다(DS 8.1 forced-colors 항목).
|
||||
4. 스크린 리더로만 아는 것.
|
||||
- 생성 폼 빈 제출: `ErrorSummary`의 `role="alert"`와 첫 필드 focus가 같은 오류를 두 번 읽는가(함정 9).
|
||||
- 라우트 로딩: `LoadingSurface`의 고정 `aria-busy="true"` live region이 "불러오는 중"을 한 번도 읽지 않는가.
|
||||
- 같은 story의 TextArea: 글자 수 `<output>` 발표(A11Y-17).
|
||||
5. 셸 세션 버튼에서 로그인을 실패시킨 뒤 세 엔진에서 실제 `document.activeElement`가 무엇인가(A11Y-03). 이 repo는 1103/08-02에서 꺼진 버튼이 focus를 `body`로 떨어뜨리는 것을 이미 관찰했다.
|
||||
|
||||
## 2. 발견
|
||||
|
||||
### A11Y-01 FE-GATE-028이 지난 release에 서명한 수동 기록을 새 release 후보에서도 통과시킨다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함 · 21, 5, 10, 7 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Medium·P2 · M1(checklist에 규칙만 있다) · E1 |
|
||||
| 근거 | `scripts/verify-a11y-manual.ts:61-68`은 기록끼리 Release ID가 하나인지(`releaseIds.size === 1`)만 본다. 환경값·인자로 후보 ID를 받지 않는다(파일 안에 `process.env`가 없다). release 스크립트(`scripts/{check-release-admission,create-release-candidate,verify-release-candidate,verify-release}.ts`)는 a11y 보고서를 읽지 않는다. 약속은 `docs/accessibility/manual-checklist.md:3-4`(「한 release 후보에 대해」)와 `:8-11`(「맞지 않는 release ID」를 거부, 「release 후보마다 한 번 필요하다」)이다 |
|
||||
| 발생 조건 | 첫 release에서 세 기록에 같은 Release ID로 서명한다. 그 뒤 화면을 바꾸고 기록은 그대로 둔 채 다음 release를 돈다 |
|
||||
| 영향 | release 게이트가 "이번 후보를 사람이 검토했다"는 증거 없이 PASS를 낸다(결함 패턴 G7, 「이전 release를 보고 통과」). 아직 서명한 release가 없어 지금 피해는 없다. 그래서 P1이 아니라 P2다 |
|
||||
| 최소 개선 방향 | release job이 후보 ID를 넘긴다. 예: 태그 ref. workflow의 `RELEASE_ID`는 run마다 달라 사람이 미리 적을 수 없으니 그대로 쓸 수 없다. `verify-a11y-manual.ts`는 기록의 Release ID가 그 값과 다르면 실패한다. 어떤 ID를 쓸지는 소유자 결정이다(`decisions.md` 3절 형식) |
|
||||
| 완료 기준 | 모든 기록이 옛 ID로 서명된 상태에서 FE-GATE-028이 실패한다. 후보 ID와 같으면 통과한다 |
|
||||
| RED 시험 | `tests/unit/manual-a11y-evidence.test.ts`에 사례를 더한다: 세 기록이 `r1`로 서명, 후보 `r2` → 실패를 기대. 지금은 통과한다. 실험 E-L5-08 |
|
||||
|
||||
### A11Y-02 라우트 heading의 focus 표시를 키보드 사용자에게서도 지운다. M2를 모든 라우트에서 통과할 수 없다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함 · 1, 23, 10 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low·P2 · M1 · E1 |
|
||||
| 근거 | `src/presentation/styles/theme/templates.css:7-9` `[data-route-heading]:focus { outline: none; }`. 이 줄은 `@layer components`에 있다. 그래서 `@layer base`의 `:focus-visible` 표시(`base.css:77-80`)보다 layer 순서로 이긴다. 그 h1은 라우트를 옮길 때마다 focus를 받는다(`components/page-header.tsx:25-42`, `routes/app-router.tsx:187-189`). 금지 패턴: routing 설계 11절 「route heading focus outline을 CSS로 무조건 제거」, 6.3절, fe-a11y 함정 6. checklist M2는 「focus를 받은 모든 요소에 눈에 보이는 표시」다(`manual-checklist.md:52`) |
|
||||
| 발생 조건 | 키보드로 셸 탐색 링크에서 Enter를 누른다. 첫 진입도 마찬가지다 |
|
||||
| 영향 | 키보드 사용자는 라우트를 옮긴 직후 focus 위치를 보지 못한다. 정직한 리뷰어라면 세 라우트 모두 M2를 pass로 적을 수 없다. 그래서 FE-GATE-028 서명을 막는다. 다운스트림의 모든 라우트가 복제한다 |
|
||||
| 최소 개선 방향 | `[data-route-heading]:focus:not(:focus-visible) { outline: none; }`. 마우스 사용자만 표시를 줄이고, 키보드 사용자는 `:focus-visible` 표시가 남는다 |
|
||||
| 완료 기준 | 키보드로 이동한 뒤 h1의 `outline-style`이 세 엔진에서 `solid`다. 마우스로 클릭해 이동했을 때는 `none`이다 |
|
||||
| RED 시험 | e2e: `#primary-navigation`의 「플랫폼 구성」 링크에 focus를 두고 Enter → h1이 focus되고 `outline-style`이 `solid`인지 본다. 지금은 `none`이라 실패한다. 실험 E-L5-03 |
|
||||
|
||||
### A11Y-03 셸 세션 버튼과 로그인 안내 버튼이 처리 중에 `disabled`가 되어 키보드 focus를 잃는다. 템플릿 action API에는 `pending`이 없다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함 · 1, 6, 28, 23 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low·P2 · M1 · E1(focus를 잃는다는 사실은 이 repo가 1103/08-02에서 실제로 관찰했다) |
|
||||
| 근거 | 셸: `layouts/app-shell.tsx:95-111` `disabled={sessionAction.pending}`. 보호 라우트: `routes/app-router.tsx:289-298` `disabled: pending`. 템플릿 API: `templates/page-templates.tsx:18-25`(`PageActionDefinition`에 `pending` 칸이 없음), `:285-292`(`disabled={action.disabled}`). 같은 파일 `:271-272` 주석은 "누른 버튼을 다시 마운트하지 않는다"고 하면서 버튼을 끈다. 시험이 이 동작을 고정한다: `tests/component/route-status-surfaces.test.tsx:99`, `:119` `toBeDisabled()`. 규칙: `docs/manual/02-decision-tables.md:377`(「꺼진 버튼은 키보드 포커스를 잃는다」), DS 5.1 `:319`, fe-a11y 함정 4. 같은 모양이 `design-system/primitives/pagination.tsx:35-60`에도 있다. 2쪽에서 「이전」을 누르면 1쪽이 되며 그 버튼이 꺼진다. 템플릿 소비자는 없다 |
|
||||
| 발생 조건 | 키보드로 로그인·로그아웃·세션 복구를 누른다. 특히 실패하는 경우다. 실패하면 `role="alert"`만 뜨고 버튼은 다시 켜지지만 focus는 돌아오지 않는다 |
|
||||
| 영향 | 실패 전이 뒤 키보드·스크린 리더 사용자가 위치를 잃는다(결함 패턴 C11). 공개 라우트에서는 다른 focus 이동도 없다. 모든 다운스트림의 셸이 복제한다 |
|
||||
| 최소 개선 방향 | `PageActionDefinition`의 button에 `pending`을 더하고 `Button`의 `pending`을 쓴다. 셸 세션 버튼도 `pending`으로 바꾼다. 중복 실행은 `sessionAction.run` 쪽에서 막는다. Pagination 경계 버튼은 `aria-disabled`와 클릭 무시로 바꾼다 |
|
||||
| 완료 기준 | 처리 중에도 버튼이 `disabled`가 아니고 `aria-busy="true"`다. 실패 뒤 focus가 그 버튼에 남는다(세 엔진) |
|
||||
| RED 시험 | `route-status-surfaces.test.tsx`의 두 사례를 고친다: `not.toBeDisabled()` + `toHaveAttribute("aria-busy","true")` + 거절 뒤 `toHaveFocus()`. 지금은 실패한다 |
|
||||
|
||||
### A11Y-04 예제 화면을 Storybook으로 옮기며 갤러리 전체 axe 검사가 빠졌다. 라우트에 없는 primitive 상태는 어느 게이트도 axe로 보지 않는다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 구조적 위험 · 10, 21, 27 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low·P2 · M0(갤러리에만 있는 상태에는 자동 검사가 없음을 확인) · E1 |
|
||||
| 근거 | 전에는 `/examples/ui`·`/examples/states`가 등록 라우트였다. 그래서 `tests/e2e/accessibility.spec.ts:35-96`이 화면 전체를 WCAG 태그로 검사했다(`bbde570`의 gates.json 수동 기록 목록에 `EXAMPLES_UI`·`EXAMPLES_STATES`가 있다). `c7e80f2f`가 옮긴 시험 목록에 이 라우트 스캔은 없다. 지금 상태: (1) `tests/storybook/galleries.spec.ts:58-71`은 `.include(".ui-dialog")`만 검사한다. (2) `ScreenStates` story는 시각 골든만 찍는다(`tests/visual/platform.visual.spec.ts:114`). (3) workshop은 `OverlayInteraction`만 검사하고 `Primitives` story는 검사하지 않는다(`tests/storybook/workshop.spec.ts:15-25`). (4) `.storybook/preview.tsx:118-120`의 `a11y.test: "error"`는 돌리는 runner가 없다(두 spec 모두 `a11y.manual`). fe-a11y 「검증」의 「story axe `tests/storybook/`」는 실제보다 넓게 적었다 |
|
||||
| 발생 조건 | gallery에만 있는 상태를 망가뜨린다: TextArea·RadioGroup·ProgressBar·Switch, Badge `info`·`danger`, Alert 변형, 상태 화면 갤러리 등 |
|
||||
| 영향 | 이름·연결·대비가 회귀해도 merge 게이트가 통과한다(결함 패턴 T10). `check:design-system`이 대비를 보는 것은 focus 색(UI-01)뿐이다 |
|
||||
| 최소 개선 방향 | `galleries.spec.ts`에서 `DesignSystem`·`ScreenStates` story 전체를 WCAG 태그로 검사한다. 밝은 테마와 어두운 테마 둘 다다. fe-a11y 「검증」 문장도 검사 범위에 맞춘다 |
|
||||
| 완료 기준 | 실험 E-L5-02의 변이(TextArea label 연결 끊기)가 `test:storybook`에서 `label` 위반으로 실패한다 |
|
||||
| RED 시험 | E-L5-02. 지금은 FE-GATE-006·008·009가 모두 통과할 것으로 예상한다 |
|
||||
|
||||
### A11Y-05 WCAG 2.2에서 새로 생긴 AA 기준은 자동 검사도 수동 checklist도 보지 않는다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 구조적 위험 · 10, 21, 5 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low·P2 · M1(`PRODUCT.md`에 「WCAG 2.2 AA를 기준」만 있다) · E1 |
|
||||
| 근거 | axe 태그는 2.0·2.1까지다: `tests/e2e/accessibility.spec.ts:13`, `generated-feature.spec.ts:31`, `theme.spec.ts:14`, `tests/storybook/galleries.spec.ts:65`. axe 4.12의 `target-size`(`wcag22aa`)를 쓰지 않는다. 수동 항목은 M1~M7 + 스크린 리더뿐이다: `manual-checklist.md:24-56`, `scripts/lib/manual-a11y-evidence.ts:7-16`, `scripts/create-feature.ts:1595-1610`. 2.4.11 포커스 가림·2.5.7 드래그·2.5.8 목표 크기·3.3.8 인증과 A 등급의 3.2.6·3.3.7을 볼 칸이 없다. 함정 1은 자동 검사가 못 본다고 적었지만, 그것을 대신할 수동 항목이 없다 |
|
||||
| 발생 조건 | 화면에 고정 요소(sticky 폼 버튼, toast)를 두거나 작은 대상을 쓰는 다운스트림 |
|
||||
| 영향 | release 서명이 통과해도 약속한 2.2 AA 일부는 아무도 확인하지 않는다 |
|
||||
| 최소 개선 방향 | (1) 태그에 `wcag22aa`를 더한다. 실험 E-L5-04로 지금 위반이 있는지 먼저 본다. (2) checklist·기록 양식·`REVIEW_FIELDS`·생성 기록에 2.4.11과 2.5.8(+드래그) 항목을 더한다 |
|
||||
| 완료 기준 | 네 spec의 태그에 `wcag22aa`가 있다. 기록 양식에 새 항목이 있고 검사기가 그 칸을 요구한다 |
|
||||
| RED 시험 | `tests/unit/manual-a11y-evidence.test.ts`: 2.4.11 칸이 없는 기록을 format 검사가 거부한다. 지금은 통과한다 |
|
||||
|
||||
### A11Y-06 Tooltip이 1.4.13 hoverable을 지키지 않는다. 포인터를 설명 위로 옮기면 사라진다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함 · 1, 24, 10 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low·P2 · M1(컴포넌트 주석이 1.4.13을 주장한다) · E1(CSS 판독) |
|
||||
| 근거 | `design-system/primitives/tooltip.tsx:8-12`는 1.4.13을 주장하지만 Escape(dismissable)만 처리한다. `styles/theme/primitives.css:502-522`: 설명은 trigger 위 `calc(100% + var(--space-2))` 거리에 있다. 거기에 `pointer-events: none`이고, `.ui-tooltip:hover`일 때만 `opacity: 1`이다. 그래서 포인터가 틈을 건너거나 설명 위에 있으면 hover가 풀려 숨는다. 시험(`tests/component/tooltip.test.tsx`)은 jsdom이라 CSS를 보지 않는다 |
|
||||
| 발생 조건 | 마우스·확대 사용자가 설명을 읽으려고 포인터를 그 위로 옮긴다 |
|
||||
| 영향 | WCAG 2.2 AA 1.4.13 실패. 템플릿 라우트에서는 쓰지 않는다(gallery뿐). Tooltip을 쓰는 다운스트림 화면은 모두 실패한다 |
|
||||
| 최소 개선 방향 | 설명의 `pointer-events: none`을 없앤다. 틈은 padding이나 `::before` 다리로 메워 hover 영역을 잇는다 |
|
||||
| 완료 기준 | trigger에 hover → 설명 중앙으로 이동 → 설명이 보인다(세 엔진) |
|
||||
| RED 시험 | `tests/storybook/galleries.spec.ts`: 「도움말」에 hover → `page.mouse.move`로 tooltip 중앙 → `opacity` 1을 기대. 지금은 실패한다. 실험 E-L5-06 |
|
||||
|
||||
### A11Y-07 셸 modal drawer가 모든 라우트에 있는데 라우트 기록 셋이 M4를 "modal 없음"으로 채웠다. checklist는 그 기록을 복사해 시작하라고 한다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함 · 5, 21, 23, 26 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low·P2 · M1 · E1 |
|
||||
| 근거 | `docs/accessibility/route-reviews/{APP_HOME,EXAMPLES_PLATFORM,NOT_FOUND}.md:13`은 `M4 Modal focus: not-applicable (no modal on this route)`다. 하지만 `layouts/app-shell.tsx:126-144`가 모든 셸 라우트에 modal `Drawer`(`showModal`)를 둔다. 48rem 미만에서 메뉴 버튼이 연다(`responsive.css:13-15`). 규칙: `manual-checklist.md:60-61`(「dialog가 있는 route는 … not-applicable로 표시하면 안 된다」). 같은 문서 `:20-21`은 「pending 기록 하나를 복사하고 제목과 Route ID만 바꿔서 시작」하라고 한다. 그래서 손으로 만든 폼 라우트도 M4·M5가 n/a로 시작한다. 검사기는 모든 `not-applicable (...)`를 받는다(`scripts/lib/manual-a11y-evidence.ts:28`, `:60-65`, `:86-93`). `create:feature`가 만드는 기록만 M4·M5를 pending으로 둔다(`scripts/create-feature.ts:1605-1606`) |
|
||||
| 발생 조건 | 리뷰어가 미리 채운 n/a를 그대로 두고 서명한다. 손으로 라우트를 더한 제품이 문서대로 기록을 복사한다 |
|
||||
| 영향 | 셸 drawer의 focus 가두기·복원은 사람 검토에서 빠진다. 폼 라우트의 M5도 빠진 채 FE-GATE-028을 통과할 수 있다 |
|
||||
| 최소 개선 방향 | 세 기록의 M4를 `pending`으로 바꾼다. checklist의 복사 안내는 생성 기록 양식(M4·M5 pending)을 가리키게 한다. 검사기는 셸 라우트의 M4 `not-applicable`을 거부한다 |
|
||||
| 완료 기준 | 셸 아래 라우트 기록의 M4가 n/a면 `review:a11y-manual -- --format-only`가 실패한다 |
|
||||
| RED 시험 | `tests/unit/manual-a11y-evidence.test.ts`: 커밋된 기록마다 M4가 n/a가 아님을 기대한다. 지금 세 기록에서 실패한다 |
|
||||
|
||||
### A11Y-08 reduced-motion e2e가 규칙을 지워도 통과한다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함(시험) · 10, 21 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low·P3 · M2(규칙은 구현됨. 자동 검사가 위반을 못 잡는다) · E1 |
|
||||
| 근거 | `tests/e2e/accessibility.spec.ts:130-137`은 `body`의 `animationDuration`이 `["0s","0.00001s","1e-05s"]` 중 하나인지 본다. `body`에는 animation이 없어 기본값 `0s`가 늘 나온다. 그래서 `responsive.css:86-95` 블록을 지워도 통과한다(결함 패턴 T2). 실제로 animation이 있는 것은 `.ui-spinner`뿐이다(`primitives.css:116`). 라우트 기록 Notes(`APP_HOME.md:18`)는 이 시험을 「reduced-motion evidence」로 든다 |
|
||||
| 발생 조건 | reduced-motion 규칙이 지워지거나 깨진다 |
|
||||
| 영향 | M7 자동 증거가 늘 참이다 |
|
||||
| 최소 개선 방향 | 허용 목록에서 `0s`를 뺀다. animation이 있는 요소(Spinner)에서 `animationDuration`이 `1e-05s`·`0.00001s`이고 `animationIterationCount`가 `1`인지 본다. 대조로 `no-preference`에서는 원래 값인지도 본다 |
|
||||
| 완료 기준 | E-L5-01 변이에서 시험이 실패한다 |
|
||||
| RED 시험 | E-L5-01. 지금은 변이에서도 통과할 것으로 예상한다 |
|
||||
|
||||
### A11Y-09 fe-a11y·fe-ux 스킬은 제출 실패 때 오류 요약으로 focus가 간다고 적었다. 코드·시험·fe-qa는 첫 오류 필드다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함(문서) · 23, 9, 4 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low·P3 · M1 · E1 |
|
||||
| 근거 | 스킬: `.claude/skills/fe-a11y/SKILL.md:54`, `.claude/skills/fe-ux/SKILL.md:61`(「오류 요약으로 포커스」) vs `.claude/skills/fe-qa/SKILL.md:59`(「첫 오류로 포커스」). 코드: `src/presentation/forms/use-app-form.ts:158-163`, `:296`, `:369`. 시험: `tests/e2e/generated-feature.spec.ts:185-189`, `tests/component/form-foundation.test.tsx:219-228`. 출처 기록 문서도 5.2절(first-invalid)과 8.3절(summary)이 서로 다르다 |
|
||||
| 발생 조건 | 이 렌즈로 리뷰하거나 고치는 세션 |
|
||||
| 영향 | 맞는 코드를 결함으로 올리거나, 시험을 깨는 수정을 낸다. 같은 사실의 손 사본이 이미 갈라졌다 |
|
||||
| 최소 개선 방향 | 두 스킬 문장을 코드에 맞춘다: 「첫 오류 필드로 focus, 요약은 `role="alert"`로 알림」. 출처는 `use-app-form.ts`로 둔다 |
|
||||
| 완료 기준 | 세 스킬이 같은 동작을 적는다 |
|
||||
| RED 시험 | 시험 없음(문서). `scripts/verify.sh docs`로 확인 |
|
||||
|
||||
### A11Y-10 Popover가 이름 없는 `role="dialog"`를 그린다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함 · 1, 24 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low·P3 · M1(DS 8.1 「accessible name이 있다」) · E1 |
|
||||
| 근거 | `design-system/primitives/popover.tsx:53`에 `aria-label`·`aria-labelledby`가 없다. ARIA는 dialog에 이름을 요구한다. axe `aria-dialog-name`은 best-practice라 WCAG 태그 스캔은 못 잡는다. 시험은 이름 없는 dialog를 고정한다(`tests/component/design-system-platform.test.tsx:322`, `getByRole("dialog")`) |
|
||||
| 발생 조건 | Popover를 연다 |
|
||||
| 영향 | 스크린 리더가 "대화상자"라고만 읽는다. 지금 템플릿 소비자는 없다 |
|
||||
| 최소 개선 방향 | trigger에 id를 주고 content에 `aria-labelledby={triggerId}`를 단다 |
|
||||
| 완료 기준 | `getByRole("dialog", { name: triggerLabel })`로 찾힌다 |
|
||||
| RED 시험 | 위 단언으로 바꾸면 지금 실패한다 |
|
||||
|
||||
### A11Y-11 Dialog 안의 Menu·Popover·Tooltip에서 Escape를 누르면 Dialog까지 닫힌다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 구조적 위험 · 1, 22 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low·P3 · M1(DS 8.2 중첩 overlay) · E1 |
|
||||
| 근거 | `dialog.tsx:111-116`의 `onKeyDown`은 모든 Escape에 `onClose()`를 부르고 `event.defaultPrevented`를 보지 않는다. Menu는 content에서 `preventDefault`만 하고 전파를 막지 않는다(`menu.tsx:100-104`). 포털이 없어 React 이벤트가 dialog까지 올라간다. Popover·Tooltip은 document listener다(`popover.tsx:27-34`, `tooltip.tsx:16-24`) |
|
||||
| 발생 조건 | modal 안에 Menu·Popover·Tooltip을 둔다. 템플릿에는 아직 없다 |
|
||||
| 영향 | 안쪽 overlay만 닫으려던 Escape가 modal을 닫는다. 폼 dialog라면 입력을 잃는다 |
|
||||
| 최소 개선 방향 | Dialog의 Escape 처리가 `event.defaultPrevented`면 넘긴다. Popover·Tooltip은 Escape를 처리하면 `preventDefault`한다(capture 순서는 시험으로 확인) |
|
||||
| 완료 기준 | 중첩 상태에서 Escape 한 번이면 안쪽만 닫히고 focus가 안쪽 trigger로 간다 |
|
||||
| RED 시험 | E-L5-07 component 시험. 지금은 실패할 것으로 예상한다 |
|
||||
|
||||
### A11Y-12 Menu가 열린 채 Tab으로 focus가 빠져나간다. 그 뒤에는 Escape로 닫지 못한다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함 · 1 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low·P3 · M1(DS 5.1 Menu 「Escape」) · E1 |
|
||||
| 근거 | `menu.tsx:58-71`은 바깥 `pointerdown`에서만 닫는다. Escape는 menu content의 `onKeyDown`에만 있다(`:100-104`). Tab·blur 처리가 없다 |
|
||||
| 발생 조건 | 키보드로 menu를 열고 Tab |
|
||||
| 영향 | 열린 menu가 다음 focus 대상을 덮을 수 있다(2.4.11, 확인 못 한 것). 다시 menu 안으로 돌아와야 닫힌다 |
|
||||
| 최소 개선 방향 | content의 `onKeyDown`에서 Tab이면 닫는다(APG). 또는 focusout으로 root 밖으로 나가면 닫는다 |
|
||||
| 완료 기준 | Tab 뒤 `queryByRole("menu")`가 없다 |
|
||||
| RED 시험 | `design-system-platform.test.tsx`에 menu 열기 → `user.tab()` → 닫힘 기대를 더한다. 지금은 실패한다 |
|
||||
|
||||
### A11Y-13 required 표시가 primitive마다 다르다. SearchField는 기호만 있고 Checkbox는 상태만 있다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함 · 1, 23 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low·P3 · M1(DS 8.3 「required는 시각적 기호와 programmatic 상태를 함께」) · E1 |
|
||||
| 근거 | `search-field.tsx:25`는 `required`를 꺼내 `Field`(기호 `*`, `field.tsx:45`)에만 넘긴다. `<input>`(`:43-52`)에는 넘기지 않는다. `checkbox.tsx:31-45`는 `required`가 `...props`로 input에 가지만 기호가 없다. TextField·Select·TextArea는 둘 다 있다 |
|
||||
| 발생 조건 | `required` SearchField·Checkbox |
|
||||
| 영향 | SearchField: 보조기술이 필수인지 모른다. Checkbox: 보는 사람이 필수인지 모른다. 지금 템플릿 소비자는 없다 |
|
||||
| 최소 개선 방향 | SearchField input에 `required`를 넘긴다. Checkbox label에 `aria-hidden` 기호를 더한다 |
|
||||
| 완료 기준 | 두 primitive 모두 `toBeRequired()`이고 `*`가 보인다 |
|
||||
| RED 시험 | component: `<SearchField required …/>`의 searchbox `toBeRequired()`. 지금은 실패한다 |
|
||||
|
||||
### A11Y-14 Toast 닫기 버튼으로 닫으면 focus가 `body`로 떨어진다. DS가 요구한 focus policy가 없다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 구조적 위험 · 1, 28 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low·P3 · M1(DS 5.2 `ToastRegion` 「dismiss, focus policy」) · E1 |
|
||||
| 근거 | `toast.tsx:130-136`의 닫기는 focus된 버튼째 항목을 지운다. 돌려 둘 곳이 없다. 1105/08-01(사라지는 복구 버튼)과 같은 모양이다(결함 패턴 C11) |
|
||||
| 발생 조건 | 키보드로 toast에 들어가 닫는다 |
|
||||
| 영향 | 위치를 잃는다. 지금 템플릿 소비자는 없다(gallery뿐) |
|
||||
| 최소 개선 방향 | 닫기 전에 다음 toast의 닫기 버튼, 없으면 toast에 들어오기 전 focus(기록)로 돌린다 |
|
||||
| 완료 기준 | 닫은 뒤 `document.activeElement !== body` |
|
||||
| RED 시험 | component: toast 둘 → 첫 닫기 Enter → 둘째 닫기 버튼 `toHaveFocus()`. 지금은 실패한다 |
|
||||
|
||||
### A11Y-15 홈의 `readiness-grid`가 role 없는 `div`에 `aria-label`을 단다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함 · 1, 24 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low·P3 · M1 · E1 |
|
||||
| 근거 | `pages/home-page.tsx:56`. ARIA 1.2는 generic role의 이름을 금지한다. 보조기술은 이 이름을 버린다. axe는 내용이 있으면 "검토 필요"로만 내서 게이트가 못 잡는다 |
|
||||
| 발생 조건 | 늘(APP_HOME) |
|
||||
| 영향 | 묶음 이름 「준비 상태」가 전달되지 않는다. 다운스트림 홈이 복제한다 |
|
||||
| 최소 개선 방향 | `role="group"`을 더하거나 `<section aria-label>`·목록으로 바꾼다 |
|
||||
| 완료 기준 | `getByRole("group", { name: message("home.readiness") })`로 찾힌다 |
|
||||
| RED 시험 | `tests/component/starter-pages.test.tsx`에 위 단언을 더한다. 지금은 실패한다 |
|
||||
|
||||
### A11Y-16 공개 라우트는 Suspense가 다 풀리기 전에 axe가 돌 수 있다. 그래도 `a11y.json`은 검사한 것으로 센다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 미검증 · 10, 5, 21 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low·P3 · M1 · E1 |
|
||||
| 근거 | `tests/e2e/accessibility.spec.ts:89-94`의 공개 라우트 분기는 h1 제목만 기다린다. 보호 분기(`:69`)에는 `[aria-busy='true']` 0개 대기가 있지만 공개 분기에는 없다. EXAMPLES_PLATFORM은 HTTP 오퍼레이션 표와 그 Badge를 `Suspense` 뒤에 그린다(`examples/platform-overview-page.tsx:555-557`, LoadingSurface는 `aria-busy="true"`). 릴리스 지표 `dl`도 `aria-busy`다(`:446-449`) |
|
||||
| 발생 조건 | 기능 실행부 import가 스캔보다 늦는 실행 |
|
||||
| 영향 | 그 표가 검사됐는지 실행마다 다르다. 함정 2(본 상태를 넘겨 짐작) |
|
||||
| 최소 개선 방향 | 공개 분기에도 `await expect(page.locator("[aria-busy='true']")).toHaveCount(0)`을 넣는다 |
|
||||
| 완료 기준 | E-L5-05에서 스캔 때 busy가 늘 0이다 |
|
||||
| RED 시험 | E-L5-05(busy 개수 기록) |
|
||||
|
||||
### A11Y-17 TextArea 글자 수 `<output>`이 글자를 칠 때마다 live region으로 발표된다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 미검증 · 1 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low·P3 · M1(DS 8.1 「필요한 변경만 live region으로 한 번」, 함정 9) · E1 |
|
||||
| 근거 | `text-area.tsx:66-72`. `<output>`은 암묵 role이 `status`(polite live)다. 글자마다 값이 바뀐다. 입력과 `aria-describedby`로 잇지도 않는다 |
|
||||
| 발생 조건 | `maxLength` TextArea에 입력 |
|
||||
| 영향 | 입력마다 "N자 남음"이 끼어든다. 스크린 리더로 확인이 필요하다(1절 확인 못 한 것 4) |
|
||||
| 최소 개선 방향 | 카운터는 live가 아닌 텍스트로 두고 `aria-describedby`로 잇는다. 발표는 문턱(예: 20자 남음, 0)에서만 별도 live region으로 한 번 한다 |
|
||||
| 완료 기준 | 카운터가 live region이 아니다. 문턱에서만 발표한다 |
|
||||
| RED 시험 | component: 카운터 요소가 `role="status"`가 아님을 단언한다. 지금은 실패한다 |
|
||||
|
||||
### A11Y-18 [w2-fe-2 파일] FE-GATE-028 증거 목록이 라우트 기록을 손으로 골라 EXAMPLES_PLATFORM 기록이 빠졌다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 · 관점 | 확인된 결함 · 23, 21, 7 |
|
||||
| 심각도·우선순위 · 통제 · 증거 | Low·P3 · M0(대조 검사 없음) · E1 |
|
||||
| 근거 | `config/ci/gates.json:993-1002`, `:1985-1994`에는 `APP_HOME.md`·`NOT_FOUND.md`만 있다. 검사 범위는 레지스트리 전체(`scripts/lib/manual-a11y-evidence.ts:3-5`)로 세 라우트다. `bbde570`에도 10개 중 6개만 있었다. 손 사본이 이미 다르다(결함 패턴 S1) |
|
||||
| 발생 조건 | release run의 증거 업로드 |
|
||||
| 영향 | EXAMPLES_PLATFORM의 서명 기록 원문이 release 증거로 남지 않는다. `report.json`에는 판정 칸이 없다 |
|
||||
| 최소 개선 방향 | 증거 목록을 레지스트리에서 만들거나, 목록이 레지스트리와 같은지 `check:ci`가 대조한다 |
|
||||
| 완료 기준 | 레지스트리 라우트마다 route-review 증거 artifact가 있다 |
|
||||
| RED 시험 | unit: FE-GATE-028 `evidenceArtifactIds`가 레지스트리의 모든 라우트 기록을 덮는지 본다. 지금 EXAMPLES_PLATFORM에서 실패한다 |
|
||||
|
||||
## 3. 넘길 것
|
||||
|
||||
- → fe-design-system: A11Y-06·10·11·12·13·14·17은 공통 primitive라 고치는 곳이 `src/presentation/design-system/`이다. 페이지마다 고치지 않는다. 판정은 이 렌즈로 했다.
|
||||
- → fe-ux(디자인 결정):
|
||||
- Dialog 닫기·Alert 닫기 대상이 2rem(32px)이다(`primitives.css:362-366`). 2.5.8 최소 24는 넘지만 DS의 44 목표 밑이다.
|
||||
- 셸 테마·언어 select의 label을 시각적으로 숨긴다(`shell.css:107-118`). 값만 보이는 select가 3.3.2를 충족하는지 정해야 한다.
|
||||
- Pagination 현재 페이지가 forced-colors에서 구분되는지(배경만, `border: 0`).
|
||||
- → fe-react: A11Y-03 수정 때 `sessionAction.run`의 중복 실행 막기를 버튼 `disabled`에서 훅 쪽으로 옮겨야 한다.
|
||||
- → CI·게이트 리뷰어(w2-fe-2): A11Y-18. A11Y-01의 후보 ID 전달은 release job 설계 몫이다.
|
||||
- → fe-testing: A11Y-08·A11Y-16은 시험이 대상에 닿지 않는 모양이다(T2·함정 2).
|
||||
|
||||
## 4. 실험 요청
|
||||
|
||||
desktop에서 실험마다 작업 폴더를 되돌린다. 모두 `CI=true`.
|
||||
|
||||
| ID | 명령 | 변이 패치 | 시간 상한 | 기대 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| E-L5-01 | `scripts/verify.sh exec -- corepack pnpm exec playwright test tests/e2e/accessibility.spec.ts --grep "reduced-motion"` | 아래 P1 | 15분 | 변이에서도 3엔진 통과(A11Y-08 확인) |
|
||||
| E-L5-02 | `scripts/verify.sh gate FE-GATE-006` → `scripts/verify.sh gate FE-GATE-008` → `scripts/verify.sh gate FE-GATE-009` | 아래 P2 | 25분 | 셋 다 rc=0(A11Y-04 확인) |
|
||||
| E-L5-03 | `scripts/verify.sh exec -- corepack pnpm exec playwright test tests/e2e/accessibility.spec.ts --grep "route heading shows focus"` | 아래 P3(시험 추가만) | 15분 | 지금 3엔진 실패(`none`). `templates.css:7`을 `:focus:not(:focus-visible)`로 바꾸면 통과 |
|
||||
| E-L5-04 | `scripts/verify.sh script test:a11y` | `tests/e2e/accessibility.spec.ts:13`의 배열에 `"wcag22aa"` 추가 | 15분 | 위반 목록 기록(A11Y-05 등급 근거) |
|
||||
| E-L5-05 | `scripts/verify.sh exec -- corepack pnpm exec playwright test tests/e2e/accessibility.spec.ts --grep "examples/platform" --repeat-each 10` | 공개 분기 `:94` 뒤에 `process.stdout.write(\`busy-at-scan ${await page.locator("[aria-busy='true']").count()}\n\`);` | 15분 | 0이 아닌 값이 한 번이라도 나오면 A11Y-16 확인 |
|
||||
| E-L5-06 | `scripts/verify.sh script test:storybook` | 아래 P6(시험 추가만) | 15분 | 지금 실패(A11Y-06 확인) |
|
||||
| E-L5-07 | `scripts/verify.sh exec -- node scripts/run-vitest.ts run tests/component/design-system-platform.test.tsx` | 아래 P7(시험 추가만) | 10분 | 지금 실패(A11Y-11 확인) |
|
||||
| E-L5-08 | `scripts/verify.sh exec -- env RELEASE_ID=r9-new corepack pnpm review:a11y-manual` | 아래 P8 | 5분 | rc=0, `PASS (3 routes)`(A11Y-01 확인) |
|
||||
|
||||
P1
|
||||
|
||||
```diff
|
||||
--- a/src/presentation/styles/theme/responsive.css
|
||||
+++ b/src/presentation/styles/theme/responsive.css
|
||||
@@ -86,10 +86,0 @@
|
||||
-@media (prefers-reduced-motion: reduce) {
|
||||
- *,
|
||||
- *::before,
|
||||
- *::after {
|
||||
- scroll-behavior: auto !important;
|
||||
- animation-duration: 0.01ms !important;
|
||||
- animation-iteration-count: 1 !important;
|
||||
- transition-duration: 0.01ms !important;
|
||||
- }
|
||||
-}
|
||||
```
|
||||
|
||||
P2
|
||||
|
||||
```diff
|
||||
--- a/src/presentation/design-system/primitives/text-area.tsx
|
||||
+++ b/src/presentation/design-system/primitives/text-area.tsx
|
||||
@@ -55,3 +55,3 @@
|
||||
defaultValue={value === undefined ? defaultValue : undefined}
|
||||
- id={controlId}
|
||||
+ id={undefined}
|
||||
maxLength={maxLength}
|
||||
```
|
||||
|
||||
P3 (`tests/e2e/accessibility.spec.ts` 끝에 추가)
|
||||
|
||||
```diff
|
||||
+test("@a11y route heading shows focus after keyboard navigation", async ({ page }) => {
|
||||
+ await page.goto("/");
|
||||
+ await expect(page.getByRole("heading", { level: 1 })).toBeFocused();
|
||||
+ await page.locator('#primary-navigation a[href$="/examples/platform"]').focus();
|
||||
+ await page.keyboard.press("Enter");
|
||||
+ const heading = page.getByRole("heading", { level: 1, name: "플랫폼 구성" });
|
||||
+ await expect(heading).toBeFocused();
|
||||
+ expect(await heading.evaluate((node) => getComputedStyle(node).outlineStyle)).toBe("solid");
|
||||
+});
|
||||
```
|
||||
|
||||
P6 (`tests/storybook/galleries.spec.ts` 끝에 추가)
|
||||
|
||||
```diff
|
||||
+test("keeps the tooltip while the pointer moves onto it (1.4.13)", async ({ page }) => {
|
||||
+ await openDesignSystemGallery(page);
|
||||
+ await page.getByRole("button", { name: "도움말" }).hover();
|
||||
+ const tip = page.getByRole("tooltip");
|
||||
+ await expect(tip).toHaveCSS("opacity", "1");
|
||||
+ const box = await tip.boundingBox();
|
||||
+ await page.mouse.move(box!.x + box!.width / 2, box!.y + box!.height / 2, { steps: 5 });
|
||||
+ await expect(tip).toHaveCSS("opacity", "1");
|
||||
+});
|
||||
```
|
||||
|
||||
P7 (`tests/component/design-system-platform.test.tsx`의 `describe("design-system platform interactions")` 안에 추가. `Dialog`·`Menu`는 같은 파일이 이미 쓰는 design-system 배럴에서 import에 더한다)
|
||||
|
||||
```diff
|
||||
+ it("closes only a menu inside a modal on Escape", async () => {
|
||||
+ const user = userEvent.setup();
|
||||
+ const onClose = vi.fn();
|
||||
+ render(
|
||||
+ <Dialog open onClose={onClose} title="바깥">
|
||||
+ <Menu triggerLabel="안쪽 메뉴" items={[{ id: "a", label: "가", onSelect() {} }]} />
|
||||
+ </Dialog>,
|
||||
+ );
|
||||
+ await user.click(screen.getByRole("button", { name: "안쪽 메뉴" }));
|
||||
+ await waitFor(() => expect(screen.getByRole("menuitem", { name: "가" })).toHaveFocus());
|
||||
+ await user.keyboard("{Escape}");
|
||||
+ expect(screen.queryByRole("menu")).not.toBeInTheDocument();
|
||||
+ expect(onClose).not.toHaveBeenCalled();
|
||||
+ });
|
||||
```
|
||||
|
||||
P8 (세 기록을 같은 꼴로. `APP_HOME.md` 예)
|
||||
|
||||
```diff
|
||||
--- a/docs/accessibility/route-reviews/APP_HOME.md
|
||||
+++ b/docs/accessibility/route-reviews/APP_HOME.md
|
||||
@@ -3,16 +3,16 @@
|
||||
-Status: pending-manual-review
|
||||
+Status: reviewed
|
||||
Route ID: APP_HOME
|
||||
-Release ID:
|
||||
-Reviewer:
|
||||
-Reviewed at:
|
||||
-Signature:
|
||||
-Attestation: pending
|
||||
-M1 Keyboard: pending
|
||||
-M2 Visible focus: pending
|
||||
-M3 Route focus: pending
|
||||
+Release ID: r8-old
|
||||
+Reviewer: probe
|
||||
+Reviewed at: 2026-01-01T00:00:00Z
|
||||
+Signature: probe
|
||||
+Attestation: accepted
|
||||
+M1 Keyboard: pass
|
||||
+M2 Visible focus: pass
|
||||
+M3 Route focus: pass
|
||||
M4 Modal focus: not-applicable (no modal on this route)
|
||||
M5 Error association: not-applicable (no form error on this route)
|
||||
-M6 Color signal: pending
|
||||
-M7 Reduced motion: pending
|
||||
-Screen reader: pending
|
||||
+M6 Color signal: pass
|
||||
+M7 Reduced motion: pass
|
||||
+Screen reader: pass
|
||||
```
|
||||
|
||||
## 5. 결함 아님으로 판정한 의심
|
||||
|
||||
- Dialog 첫 focus가 닫기(X) 버튼이다. 의미 있는 안전한 위치다. gallery 시험이 이 동작을 고정한다(`galleries.spec.ts:49-51`). selector의 `[autofocus]` 우선순위가 틀렸지만 쓰는 곳이 0이다(React는 `autofocus` 속성을 그리지 않는다).
|
||||
- Dialog Escape에서 `onCancel`과 `onKeyDown`이 둘 다 `onClose`를 부를 수 있다. keydown의 `preventDefault`가 cancel을 막고, 두 번 불려도 결과가 같다.
|
||||
- 라우트 이동 focus: `RouteLifecycle`이 main으로 focus를 옮기고 `PageHeader`가 h1로 넘긴다. 형제 effect 순서가 맞고 e2e가 고정한다(`app-shell.spec.ts:22-24`, `:60-72`).
|
||||
- 청크 실패 화면의 h1에 focus가 가지 않는다. 그래도 focus는 그 화면을 담은 main에 있고, 화면이 `role="alert"`로 알린다.
|
||||
- 생성 작성 폼의 저장 버튼은 `pending`이다. `effectUnknown` 때 `disabled`가 되는 것은 feedback 자리로 focus를 옮겨 보완한다(1103/08-02 수정, e2e `generated-feature.spec.ts:265-304`).
|
||||
- 409 충돌은 feedback 자리가 비어 focus를 옮기지 않는다. 버튼이 `pending`(켜짐)이라 focus가 남고 ErrorSummary alert가 알린다.
|
||||
- 플랫폼 구성 화면은 한국어 고정 문구이지만 `lang="ko-KR"`로 감싼다(`platform-overview-page.tsx:423`). 3.1.2를 충족한다.
|
||||
- Badge·탐색 활성·세션 상태는 글자나 `aria-current`, 굵기로도 상태를 전한다. 색만으로 전하지 않는다.
|
||||
- `DataTable` 스크롤 wrapper는 이름 있는 region이고 `tabIndex=0`이다(UI-08 시험).
|
||||
- Tabs의 manual 모드에서 tablist에 다시 들어오면 마지막 focus 탭으로 간다. 이것은 APG 권고 차이일 뿐 WCAG 실패나 repo 약속 위반이 아니다.
|
||||
- 부팅 오류 화면의 `<main role="alert">`가 main landmark를 덮는다. 부팅 실패 한 화면이고, landmark는 best-practice다.
|
||||
- 수동 기록 3개가 `pending-manual-review`다. 서명은 release 게이트 몫이라는 결정대로다(merge는 형식만 본다).
|
||||
- 라우트 기록 본문이 영어다. `scripts/lib/docs-system.ts:96`이 기록을 문서 검사에서 빼는 데이터 양식이다.
|
||||
- axe가 critical·serious만 막는 것은 함정 1과 checklist에 적힌 설계다.
|
||||
@@ -0,0 +1,342 @@
|
||||
# round9 L6 — 성능·빌드 비대화 (렌즈 fe-performance)
|
||||
|
||||
> round9 리뷰(2026-11-12, 대상 main `5250ff95`)의 영역 기록이다. 서브에이전트가 쓴 원문을 그대로 옮겼다. 바꾼 것은 이 인용 블록과, 작업 폴더 절대 경로를 `(작업 폴더)`로 줄인 것뿐이다. 발견 ID는 이 파일의 이름표(R-01 등)이고, 라운드 ID(`1112/NN-MM`)와의 대응은 [README](2026-11-round9-review.md) 15절이다.
|
||||
|
||||
|
||||
대상 커밋 `5250ff95`(origin/main). 리뷰 중 repo 파일은 고치지 않았다. 노트북에서 pnpm·node·빌드를 돌리지 않았다. desktop은 총괄의 merge 실행(`/tmp/claude-gates/r9fe-base/`) 산출물을 읽기만 했다. 사본은 이 scratchpad의 `r9fe/`(dist, bundle.json, module inventory, 게이트 로그 005·008·012·020)에 있다.
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- 판정: **고칠 것 있음**. 발견 9건 = Medium·P2 2건, Low·P3 7건(그중 `[w2-fe-2 파일]` 1건, 개선 제안 2건). High 이상 없음.
|
||||
- 번들 예산과 기준선은 지금 빌드와 맞는다. FE-GATE-012 PASS(초기 JS 194,403 / 206,848 B, 17 / 32 파일, desktop, CI env, 커밋 `b693d36`=트리 `75cc3752`). 기록 `feature-shape-ceilings.json`의 `initialJavascript`(194,354 B, 17 파일)과 49 B 차이다. 허용치 256 B 안이고 FE-GATE-005가 통과했다. 여유는 12,445 B, 생성 기능으로 약 12개다(첫 기능 6,327 B + 기능당 539 B).
|
||||
- 새로 본 위험은 둘이다. ① context 진입이 그 context의 **모든 기능 실행부**를 받을 때까지 화면을 그리지 않는다(PF-01). ② Service Worker를 켜면 정적 자산 256개 상한 때문에 생성 기능 약 25개에서 빌드가 멈추는데, 규모 기록은 이 한계를 적지 않는다(PF-02).
|
||||
- 빌드 산출물에서 확인한 비대화: Tailwind가 docs·tests·scripts의 낱말로 유틸리티 35개를 만들어 render-blocking CSS에 싣는다(PF-03). build id에 묶인 `boot` 청크에 zod·@tanstack·lucide가 있어 release마다 초기 JS의 42.7%를 다시 받는다(문서는 22%, PF-04). 꺼진 Service Worker의 페이지 컨트롤러 약 3.0 KB gzip(PF-05)과 빌드 전용 schema(PF-06)가 초기 JS에 있다.
|
||||
|
||||
## 1. 범위
|
||||
|
||||
### 1.1 읽은 것
|
||||
|
||||
- 규칙: `.claude/agents/reviewer.md`, 루트 `AGENTS.md`, `docs/work/reference/review-criteria.md`, `decisions.md`, `defect-patterns.md` B1~B4, `docs/work/reference/performance.md`
|
||||
- 렌즈 정본: `config/performance/budgets.json`, `docs/operations/performance-evidence.md` 전부, `docs/architecture/scale-architecture.md` §7·§9·§54, `docs/manual/02-decision-tables.md` 1절, `docs/operations/release-cache-rollback.md`(SW·hosting 절)
|
||||
- 설정: `vite.config.ts`, `vite.service-worker.config.ts`, `config/scale/{feature-shape-ceilings,feature-shape-growth,benchmark-baseline}.json`, `config/hosting/cache-policy.json`, `config/recipes/frontend-capability-recipes.json`(service-worker-pwa), `package.json`, `pnpm-lock.yaml` importers, `pnpm-workspace.yaml`, `index.html`, `.gitignore`, `playwright*.config.ts`의 webServer
|
||||
- 코드: `src/bootstrap/{main,boot,composition-root,create-runtime-composition,runtime-application,register-service-worker,optional-runtime-host,load-release-manifest}.ts(x)`, `src/presentation/routes/{app-router,route-runtime}.tsx`, `src/platform/routing/context-route-module.ts`, `src/application/create-application.ts`(feature loader), `src/adapters/service-worker/{index,service-worker-entry,service-worker-lifecycle}.ts`, `src/contracts/{service-worker,service-worker-static-manifest,release-artifacts,zod,runtime-capabilities}.ts`, `src/features/{installed-runtime-capabilities,product-capabilities,loaded-feature-runtimes}.ts`, `src/presentation/styles/theme.css`와 `theme/*.css`
|
||||
- 스크립트: `scripts/{build-frontend,check-bundle,test-performance,generate-build-manifest,generate-service-worker-assets,create-feature,test-feature-scaffold}.ts`, `scripts/lib/{classify-vite-bundle,lab-performance,vite-module-inventory,storybook-static,optional-recipes,hosting-probe}.ts`, `scripts/scale/measure-feature-shape-growth.ts`
|
||||
- 시험(판정 근거 확인용): `tests/unit/build-environment-bundle.test.ts`, `tests/architecture/context-lazy-loading.test.ts`, `tests/e2e/preload-use.spec.ts`·`generated-feature.spec.ts` 머리
|
||||
- `bbde570..5250ff95` 변경: 이 범위에서 바뀐 것은 `config/scale/*`, `package.json`(타입 검사 script 정리), 예제·참조 기능 삭제(2026-11-07)다. `vite.config.ts`·SW·routes는 그대로다. 바뀌지 않은 곳도 읽었다.
|
||||
|
||||
### 1.2 쓴 스킬과 그 기준으로 본 것
|
||||
|
||||
- `fe-performance` 함정 1~12와 실패 체크리스트: 예산·기준선 일치(함정 2, B1), 초기 파일 수와 HTTP/2 전제(함정 3), 청크 이름 대신 module inventory로 출처 확인(함정 4), build id 청크의 재방문 비용(함정 5, B4), 첫 화면에 필요 없는 코드(함정 6, B3), lab이 재는 범위(함정 9, B2), SW install·activate·cache 이름(함정 10), 청크 실패 reload 한 번(함정 11), `no-store`·`no-cache`·`immutable`(함정 12), 실패 메시지의 잰 값(G12).
|
||||
- brief 추가 기준: 쓰지 않는 의존성, 초기 청크의 불필요한 코드, 같은 빌드를 여러 번 하는 script, dist의 불필요한 파일·sourcemap·시험 전용 코드, 폰트·이미지 크기.
|
||||
|
||||
### 1.3 desktop 실행 결과(총괄 실행, 읽기만)
|
||||
|
||||
`/tmp/claude-gates/r9fe-base/summary.txt`: FE-GATE-001~012·020 rc=0, FE-GATE-013 rc=1(호스트 원인, D8로 merge 판정에서 뺌, 이 렌즈 밖). 성능 관련 숫자:
|
||||
|
||||
| 무엇 | 값 | 출처 |
|
||||
|---|---|---|
|
||||
| 초기 JS | 194,403 B gzip, 17 파일(예산 206,848 B, 32 파일) | `gate-artifacts/FE-GATE-012.txt` "Bundle budget: PASS" |
|
||||
| 초기 JS 기록 | 194,354 B, 17 파일, 첫 기능 6,327 B, 기능당 539 B, context당 4 B | `config/scale/feature-shape-ceilings.json:41-47` |
|
||||
| FE-GATE-020 드릴(생성 기능 둘) | 201,870 B, 23 파일 | `gate-artifacts/FE-GATE-020.txt:87` |
|
||||
| CSS | `index-3ZKFQKJV.css` 41,266 B, gzip 8,939 B(예산 밖) | `snapshot` bundle.json |
|
||||
| lazy 최대 | `platform-overview-page` 5,632 B(예산 122,880 B) | 같음 |
|
||||
| 선택 recipe 예산 | service-worker-pwa 9,814/10,100 B 등 전부 PASS | `FE-GATE-012.txt` |
|
||||
| sourcemap | dist에 `.map` 없음. 두 vite 설정 모두 `sourcemap: false` | dist 목록, `vite.config.ts:213`, `vite.service-worker.config.ts:82` |
|
||||
| 폰트·이미지 | 없음. system-ui 글꼴, `public/`은 JSON 둘 | `semantic.css:33`, `git ls-files` |
|
||||
|
||||
### 1.4 지난 성능 발견의 지금 상태
|
||||
|
||||
| ID | 지금 | 근거 |
|
||||
|---|---|---|
|
||||
| 1105/15-04 | 남음 · 결정 대기 | 생성 라우트가 여전히 `session-required`라 lab의 `labFeatureRoute`(public만, `scripts/lib/lab-performance.ts:55-68`)가 고르지 못한다(`scripts/create-feature.ts:578`). 템플릿은 기능이 없어 `measured: false`. PF-01은 이 빈틈 때문에 더 안 보인다 |
|
||||
| 1103/15-02 | 고침 확인 | `performance-evidence.md:222-226`이 숫자 대신 기록 `initialJavascript.files`를 가리킨다 |
|
||||
| 1101/15-03 | 남음 | `check-bundle.ts:49-52`가 JS만 더한다. CSS 8,939 B는 예산 밖이다(`performance-evidence.md:94`). PF-03이 그 CSS 안에서 확인됐다 |
|
||||
| 0929/11-04 | 남음 | `test-performance.ts:244-300`은 loadavg를 기록만 한다 |
|
||||
| 1101/15-01 | 고침 확인 | FE-GATE-012가 merge 단계에서 돌았다(r9fe-base) |
|
||||
| 1106/15-01 남은 부분 | 남음 | "예산 값을 규칙 밖으로 바꿔도 실패하는 시험이 없다". 지금 드릴 201,870 B면 D9 규칙 값은 199 KiB = 203,776 B다. 예산 206,848 B와 3,072 B 다르고 실패하는 시험은 없다. 3절에 소유자 몫으로 넘긴다 |
|
||||
| 0929/12-05 | 남음 | PF-09 |
|
||||
|
||||
### 1.5 확인 못 한 것
|
||||
|
||||
- lab(FE-GATE-026, release 단계)은 이번 실행에 없다. 지금 커밋의 LCP·CLS·interaction 수치는 모른다.
|
||||
- PF-01·PF-02·PF-04의 실제 비용(요청 묶음 수, 빌드 실패 지점, 다시 받는 bytes)은 실행하지 않았다. 4절 X2·X3·X4로 낸다.
|
||||
- 실제 HTTP/2 호스팅의 CSS `Cache-Control`은 보지 않았다(FE-GATE-019는 배포 슬롯이 비어 `UNVERIFIED`).
|
||||
- SW `ACTIVE` 빌드는 merge 단계에서 만들지 않는다. SW install 시간·저장량은 재지 않았다.
|
||||
|
||||
## 2. 발견
|
||||
|
||||
### PF-01 context 진입이 같은 context의 모든 기능 실행부를 받은 뒤에야 화면을 그린다
|
||||
|
||||
| 칸 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관점 | 14 성능, 13 확장성, 22 추상화 |
|
||||
| 심각도·우선순위 | Medium·P2. 기본 생성 경로(`--context`)가 닿는다. 사용자 피해는 첫 진입 지연이다. lab이 재지 못해 어느 게이트도 모른다 |
|
||||
| 통제 | M1. "바로 다음 경계만 미리 불러온다"(`scale-architecture.md:430`, 절 상태 「현재 계약」)는 적혀 있다. 실행부 적재에 대한 검사는 없다. `context-lazy-loading.test.ts`는 context 단위만 본다 |
|
||||
| 증거 | E1 |
|
||||
| 근거 | `src/presentation/routes/app-router.tsx:527-534`: `Promise.all([routeModule.loadRoutes(), loadActive([enteredOwner])])` 뒤에 `.then(async ([loaded]) => { await loadActive(routeOwners(loaded)); ... })`. 그다음에야 `setRoutes`, 그 전에는 `RouteLoadingSurface`(`:602`). `routeOwners`(`:449-461`)는 context가 가진 모든 기능이다. 그런데 그 목록은 처음부터 정적으로 있다(`src/platform/routing/context-route-module.ts:53` `featureIds`). 기능 실행부는 기능마다 따로 dynamic import다(생성기 `scripts/create-feature.ts:451`) |
|
||||
| 발생 조건 | `create:feature <id> --context <기존 context>`로 기능 둘 이상을 한 context에 넣는다(매뉴얼 `02-decision-tables.md:17-31`, 생성 context 상한 20 `create-feature.ts:116`). 그 context의 아무 라우트에 처음 들어간다 |
|
||||
| 영향 | 요청 사슬이 "라우트 모듈 + 들어간 기능 실행부 → **다른 기능 실행부 N−1개** → 페이지 청크"로 한 묶음 늘어난다. 로그인 안내 화면도 이 뒤에 그려진다. 받는 양은 기능 수에 비례한다. 기능 라우트 lab 예산 500 ms의 근거가 "같은 크기의 묶음이 하나 더 붙으면 넘는다"이다(`performance-evidence.md:129-133`). 그래서 기능 둘부터 예산을 넘을 수 있다(추론, X2로 확인) |
|
||||
| 최소 개선 방향 | (가, 작은 수정) 다른 기능 실행부 적재를 `routeModule.featureIds`로 라우트 모듈과 같은 `Promise.all`에서 시작한다. 직렬 한 단계가 없어진다. (나, 본 수정) 들어간 기능의 실행부만 기다려 그린다. 같은 context의 다른 기능 라우트로 옮겨 갈 때 그 기능을 적재한 뒤 그린다. 나머지는 뒤에서 받는다. (나)는 "`features.get`이 그 context의 모든 페이지에서 된다"(`:449-452` 주석)는 보장을 라우트 단위로 옮기는 일이라 fe-react·fe-structure 확인이 필요하다 |
|
||||
| 완료 기준 | 한 context에 기능 둘을 둔 빌드에서 둘째 기능의 실행부 응답을 붙잡아 두어도 첫째 기능 라우트의 첫 화면이 그려진다. 기능 라우트 첫 진입을 lab 조건으로 재어 결과에 적는다(`performance.md` 6절 제안) |
|
||||
| RED 시험 | X2의 spec이다. 생성 기능 둘을 한 context에 넣은 fixture 빌드에서 `beta` 실행부 청크를 3초 붙잡고 `order` 목록 주소를 연다. 로그인 안내 heading이 3초 안에 보여야 한다. 지금은 실패한다(3초 이상 기다림) |
|
||||
|
||||
### PF-02 Service Worker를 켜면 생성 기능 약 25개에서 빌드가 멈춘다. 규모 기록은 이 한계를 적지 않고, 실패 메시지는 개수를 말하지 않는다
|
||||
|
||||
| 칸 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험(기록된 측정값과 코드 상한의 산술. 지원 구성에서 재현하면 확인된 결함, X3) |
|
||||
| 관점 | 13 확장성, 14 성능, 8 디버깅, 9 유지보수 |
|
||||
| 심각도·우선순위 | Medium·P2. SW `ACTIVE`(지원 구성, `product-capabilities.ts:20-23` 주석)와 기능 수 증가가 겹치면 release 빌드가 막힌다. 기본값(SW 꺼짐)은 닿지 않는다. 기본 예산에서는 초기 JS 예산(약 12개)이 먼저 걸린다. 그러나 제품은 예산을 스스로 정하게 되어 있다(`performance-evidence.md:18-19`) |
|
||||
| 통제 | 상한 자체는 M2(`generate-service-worker-assets.ts:102-104`, 디코더 `service-worker-static-manifest.ts:137-139`). 그 한계를 규모 기록에 두는 일은 M0 |
|
||||
| 증거 | E1 |
|
||||
| 근거 | `src/contracts/service-worker.ts:14` `assets: 256`. 생성기는 `assets/` 아래 해시된 `.js`·`.css`를 모두 precache 목록에 넣는다(`scripts/generate-service-worker-assets.ts:70-101`). 기록 `config/scale/feature-shape-growth.json`의 25개 기능 run은 초기 21 + lazy 235 = JS 256개다(`:101`, `:103`). 여기에 CSS 하나를 더하면 257 > 256이다. 기능 하나는 lazy 파일 약 9.2개다. 한편 `feature-shape-ceilings.json:8` summary는 "실제 한계는 먼저 초기 JavaScript budget이고, 그다음 typecheck 메모리다"라고 적는다(typecheck는 100개까지 선형). 실패 문구 `"Static asset count exceeds its bound."`(`generate-service-worker-assets.ts:103`)에는 잰 개수도 상한도 없다(G12) |
|
||||
| 발생 조건 | `SERVICE_WORKER`를 `ACTIVE`로 하고 생성 기능을 약 25개 넣는다(`--with-create --keyed` 모양) |
|
||||
| 영향 | `corepack pnpm build`가 5단계에서 실패하고 release를 만들지 못한다. 기록은 다음 한계를 typecheck 메모리로 안내한다. 그래서 제품이 예산을 올린 뒤 이유를 모르는 빌드 실패를 만난다 |
|
||||
| 최소 개선 방향 | ① 실패 문구에 개수·상한·바이트를 넣는다. ② `feature-shape-ceilings.json` axes에 "Service Worker precache 자산 수" 축을 더한다(측정 스크립트가 기능당 자산 수를 재어 쓴다). ③ 상한을 정할지는 소유자 결정이다. 선택지: precache를 초기 청크와 라우트 청크로 줄이고 lazy 청크는 받을 때 캐시, 또는 install 비용을 재고 상한 올리기 |
|
||||
| 완료 기준 | 257개 fixture에서 실패 문구가 "257"과 "256"을 말한다. 기록에 SW 축과 그 기능 수가 있고, 측정이 그 값을 다시 쓴다. X3 결과가 기록과 같다 |
|
||||
| RED 시험 | `collectStaticAssets`에 해시 이름 `.js` 257개 fixture dist를 주면 오류 메시지가 `257`과 `256`을 담는지 본다. 지금은 실패한다 |
|
||||
|
||||
### PF-03 Tailwind가 docs·tests·scripts의 낱말로 유틸리티 35개를 만들어 render-blocking CSS에 싣는다
|
||||
|
||||
| 칸 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함(결함 패턴 B3·B4 모양) |
|
||||
| 관점 | 14 성능, 18 배포, 23 일관성 |
|
||||
| 심각도·우선순위 | Low·P3. bytes는 작다. CSS가 소스 밖 파일에 따라 달라진다 |
|
||||
| 통제 | M0. CSS는 예산 밖이고(1101/15-03) 내용 검사가 없다 |
|
||||
| 증거 | E1(지금 커밋 desktop 빌드 `dist/assets/index-3ZKFQKJV.css`를 읽음) |
|
||||
| 근거 | `src/presentation/styles/theme.css:1` `@import "tailwindcss";`에 `source(...)`가 없다. Tailwind v4는 `.gitignore`에 없는 파일을 모두 훑는다. 템플릿 TSX는 Tailwind 유틸리티 class를 쓰지 않고 `@apply`만 쓴다(`theme/primitives.css:3` 등). 빌드 CSS의 `@layer utilities`에는 35개 규칙(3,121 B)이 있다. `.collapse` `.hidden` `.container` `.table` `.grid` `.block` `.border` `.ring` `.blur` `.sepia` `.cursor-not-allowed` `.select-text` `.\!relative` `.shadow\/canary` 등이다. 출처: `shadow/canary`는 `docs/architecture/backend-api-and-server-state-contract.md:763`에만 있다. `sepia`는 `tests/unit/color-scheme.test.ts:13`, `cursor-not-allowed`는 `tests/unit/realtime/fetch-sse-connection.test.ts:733`, `!relative`는 `scripts/*`에서 왔다 |
|
||||
| 발생 조건 | 매 빌드. docs·시험·스크립트에 새 낱말이 들어올 때마다 바뀐다 |
|
||||
| 영향 | 첫 화면 CSS gzip 8,939 B 중 약 666 B(유틸리티 층만)~871 B(딸린 `@property` 포함)가 쓰이지 않는다. 문서나 시험만 고친 release도 CSS 이름이 바뀌어 재방문자가 CSS를 다시 받는다(B4). 다운스트림의 문서·시험이 제품 CSS를 바꾼다 |
|
||||
| 최소 개선 방향 | `@import "tailwindcss" source("../../");`처럼 훑는 범위를 `src/`로 좁힌다. 제품이 className에 유틸리티를 쓰지 않는 계약이면 `source(none)`이 더 좁다. 어느 쪽인지는 fe-design-system이 정한다 |
|
||||
| 완료 기준 | 빌드 CSS에 `src/` 밖에서만 나오는 유틸리티(`.shadow\/canary` 등)가 없다. docs 파일에 낱말을 더해도 CSS 이름이 같다(X1). 시각 골든이 그대로다(test:visual) |
|
||||
| RED 시험 | 빌드한 CSS에 `.shadow\/canary`가 없음을 본다. 또는 `docs/` 아래 추적 안 된 임시 파일에 `underline`을 쓰고 다시 빌드해 CSS 파일 이름이 같은지 본다. 둘 다 지금은 실패한다 |
|
||||
|
||||
### PF-04 build id만 바뀐 release가 초기 JS의 42.7%를 다시 받게 한다. 문서와 주석은 22%라고 적는다
|
||||
|
||||
| 칸 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함(문서·주석과 지금 빌드가 다름) + 구조적 위험(재방문 비용, X4로 실행 확인) |
|
||||
| 관점 | 14 성능, 18 배포, 9 유지보수 |
|
||||
| 심각도·우선순위 | Low·P3 |
|
||||
| 통제 | react-dom만 M3(`tests/unit/build-environment-bundle.test.ts:79-90`). 다른 라이브러리는 M0 |
|
||||
| 증거 | E1(module inventory·manifest·boot 청크를 읽음) |
|
||||
| 근거 | build id는 `render-boot-failure` 청크에 있다(`gitea-1-1` 문자열). `boot`는 그 파일을 해시 이름으로 import한다(boot 첫 줄 `from"./render-boot-failure-UquDXUNt.js"`). 그래서 build id가 바뀌면 boot 이름도 바뀐다(같은 구조를 `performance-evidence.md:245-248`가 2026-11-04에 쟀다). 지금 boot 청크(77,572 B)에는 `zod@4.4.3`(17 모듈), `@tanstack/query-core`(16), `@tanstack/react-query`, `lucide-react`(18), `react-router` dom-export가 들어 있다(`artifacts/quality/vite-module-inventory.json`). 이름이 바뀌는 초기 파일은 boot 77,572 + render-boot-failure 4,446 + index 897 = 82,915 B, 초기 JS의 42.7%다. 그런데 `vite.config.ts:252-254` 주석은 지금 시제로 "the same change renames 44,297 B"라고 적고, `performance-evidence.md:248`은 22.0%다. 원인(추론): zod·HTTP 실행기·계약 runtime을 고정 이름 청크로 빼던 `feature-platform` 그룹(`vite.config.ts:100-107`, `:131-135`)은 기능 실행부가 있을 때만 생긴다. 템플릿은 2026-11-07부터 기능이 없어 그것들이 boot로 돌아갔다. @tanstack·lucide는 기능 수와 상관없이 boot에 있다 |
|
||||
| 발생 조건 | 템플릿 그대로의 빌드(기능 0개)는 모든 release에서. 기능이 있는 제품은 @tanstack·lucide 몫(2026-11-01 표로 약 8.4 KB)이 남는다(추론) |
|
||||
| 영향 | 재방문자가 바뀌지 않은 라이브러리 코드를 release마다 다시 받는다. 문서를 믿고 B4가 해결됐다고 보게 된다 |
|
||||
| 최소 개선 방향 | `react-dom` 그룹처럼 zod·`@tanstack/*`·`lucide-react`를 vendor 그룹 하나로 묶는다(`includeDependenciesRecursively: false`). 초기 파일은 1개 늘고(17→18, 상한 32), HTTP/2 전제(`performance-evidence.md:222`) 안이다. 주석과 문서 표는 다시 잰 값과 커밋으로 고친다 |
|
||||
| 완료 기준 | X4에서 기능 0개·1개 빌드 모두 이름이 바뀌는 초기 JS가 문서에 적힌 값과 같다. 문서에 그 값과 커밋이 있다 |
|
||||
| RED 시험 | `build-environment-bundle.test.ts`에 react-dom과 같은 단언을 더한다. `__zod_globalRegistry`를 담은 청크 이름이 `VITE_BUILD_ID`만 다른 두 빌드에서 같아야 한다. 지금은 실패한다(boot 안에 있어 이름이 바뀜) |
|
||||
|
||||
### PF-05 꺼진 Service Worker의 페이지 컨트롤러 약 3.0 KB gzip이 초기 JS에 있다
|
||||
|
||||
| 칸 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 개선 제안(결함 패턴 B3 모양) |
|
||||
| 관점 | 14 성능, 13 확장성 |
|
||||
| 심각도·우선순위 | Low·P3 |
|
||||
| 통제 | M1(B3 규칙만 있음) |
|
||||
| 증거 | E1(boot 청크에서 그 구간을 빼고 gzip을 비교함, Python zlib 6) |
|
||||
| 근거 | `src/bootstrap/register-service-worker.ts:5`가 컨트롤러를 정적으로 import하고 boot 그래프(`optional-runtime-host.ts:12`)에 있다. 템플릿 선택은 `null`이다(`src/features/product-capabilities.ts:34`). 이때 `createServiceWorkerRuntimeHost`는 컨트롤러를 만들지 않고 `null`을 돌려준다(`register-service-worker.ts:35-37`). `serviceWorkerDisabledCleanup`도 정적 선택이 `ACTIVE`일 때만 참이다(`src/contracts/runtime-capabilities.ts:131-132`). 그래도 boot에 컨트롤러·protocol·removal·SW 상수 10,894 B(gzip 약 2,992 B)가 있다(`CLIENT_DRAIN_REQUEST`, `ACTIVATE_DRAIN_TIMEOUT` 등) |
|
||||
| 영향 | 초기 JS의 1.5%다. 기능 약 5.5개 몫(기능당 539 B)이다. 정적 선택이 `null`이면 실행되지 않는 코드다 |
|
||||
| 최소 개선 방향 | 빌드 상수(예: `vite.config.ts`의 `define`이 `INSTALLED_RUNTIME_CAPABILITIES.serviceWorker === null`을 넣음)로 `register-service-worker.ts`에서 일찍 돌아가게 해 번들러가 컨트롤러를 지우게 한다. dynamic import는 kill switch 경로가 청크 적재 실패에 기대게 되므로 권하지 않는다(관점 28) |
|
||||
| 완료 기준 | 선택 `null` 빌드의 초기 JS에 `CLIENT_DRAIN_REQUEST`가 없다. `ACTIVE`·`REMOVE_REGISTRATION` 빌드에는 있다. FE-GATE-008 SW spec이 통과한다 |
|
||||
| RED 시험 | `design-system-initial-chunk.test.ts`처럼 초기 JS를 모아 `CLIENT_DRAIN_REQUEST`가 없음을 본다. 지금은 실패한다 |
|
||||
|
||||
### PF-06 빌드 전용 schema가 초기 JS에 실려 boot 때 만들어진다
|
||||
|
||||
| 칸 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함(결함 패턴 B3: side effect 판정 때문에 쓰지 않는 코드가 남음) |
|
||||
| 관점 | 14 성능, 22 추상화 |
|
||||
| 심각도·우선순위 | Low·P3(작다) |
|
||||
| 통제 | M1 |
|
||||
| 증거 | E1(boot 청크 원문 확인) |
|
||||
| 근거 | `src/contracts/release-artifacts.ts:249-275` `buildManifestArtifactSchema`, `:201` `runtimeConfigArtifactSchema`, `:244` `releaseManifestArtifactSchema`는 `src` 안에서 아무도 쓰지 않는다(쓰는 곳은 `scripts/contracts/release-artifacts.ts:3` 재수출을 거친 스크립트뿐). zod 호출 사슬은 pure로 증명되지 않아 지워지지 않는다. boot 청크에 `K({schemaVersion:Gs(1),buildId:…,moduleInventoryHash:…,buildContext:…})`와 `Ls(\`CONFIG_SCHEMA_VERSION\`,[Lc,Rc])`, `Ls(\`schemaVersion\`,[Bc,Vc])`가 남아 있다 |
|
||||
| 영향 | 513 B(gzip 136 B). 첫 화면마다 schema 객체 셋을 만드는 CPU(4배 감속 lab 조건) |
|
||||
| 최소 개선 방향 | 이 셋과 `parse*` 함수를 `scripts/contracts/release-artifacts.ts`로 옮긴다. 또는 `/* @__PURE__ */`를 붙인다 |
|
||||
| 완료 기준 | 초기 JS에 `moduleInventoryHash`가 없다. `check:artifact-schemas`와 release 검사가 그대로 통과한다 |
|
||||
| RED 시험 | 초기 JS 문자열에 `moduleInventoryHash`가 없음을 본다. 지금은 실패한다 |
|
||||
|
||||
### PF-07 HTML이 boot 그래프를 미리 받지 않아 첫 화면 앞에 왕복이 하나 더 있다
|
||||
|
||||
| 칸 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 개선 제안 |
|
||||
| 관점 | 14 성능 |
|
||||
| 심각도·우선순위 | Low·P3 |
|
||||
| 통제 | 해당 없음 |
|
||||
| 증거 | E1(`dist/index.html`, `dist/.vite/manifest.json`) |
|
||||
| 근거 | `dist/index.html`은 entry `index-*.js`와 `preload-helper`만 `modulepreload`한다. 초기 JS의 99.2%(boot와 그 static import 15개, 192,831 B gzip)는 entry가 실행되어 `import("./boot.tsx")`(`src/bootstrap/main.tsx:14`)를 부를 때에야 요청된다. 09-03(entry가 앱 그래프를 dynamic import)의 부수 비용이고, 문서에 적힌 비용 판단은 없다 |
|
||||
| 영향 | 첫 방문마다 entry 왕복과 실행 시간만큼 LCP가 늦다. lab 조건(지연 40 ms)이면 수십 ms, Fast 3G(지연 562.5 ms)면 0.5초 규모다(추론) |
|
||||
| 최소 개선 방향 | 빌드에서 boot 청크와 그 static import를 `index.html`의 `<link rel="modulepreload">`로 넣는다(`build.modulePreload.resolveDependencies`의 html host, 또는 `transformIndexHtml` 작은 plugin). modulepreload는 평가하지 않으므로 09-03의 평가 실패 보고는 그대로다 |
|
||||
| 완료 기준 | 같은 세션에서 바꾸기 전·후를 lab 조건으로 5회씩 재어 LCP 차이를 적는다. `preload-use.spec.ts`(미리 받은 스크립트는 모두 실행됨)가 세 엔진에서 통과한다 |
|
||||
| RED 시험 | `dist/index.html`에 boot 청크 파일의 `modulepreload`가 있는지 본다. 지금은 실패한다 |
|
||||
|
||||
### PF-08 FE-GATE-008이 같은 Storybook을 두 번 빌드한다
|
||||
|
||||
| 칸 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 개선 제안 |
|
||||
| 관점 | 20 개발자 경험, 21 guardrail(실행 시간) |
|
||||
| 심각도·우선순위 | Low·P3 |
|
||||
| 통제 | 해당 없음 |
|
||||
| 증거 | E1(desktop 게이트 로그) |
|
||||
| 근거 | `scripts/lib/storybook-static.ts:18-25`가 webServer마다 `build:storybook`을 다시 부른다. `playwright.storybook.config.ts:40`과 `playwright.visual.config.ts:86`이 같은 명령을 쓴다. r9fe-base `gate-artifacts/FE-GATE-008.txt:301`과 `:321`에 같은 `storybook build -o artifacts/storybook/static`이 두 번 있다. 입력과 env가 같다(앱 빌드 둘은 identity가 달라 정당하다) |
|
||||
| 영향 | merge 게이트마다 Storybook 빌드 1회분 시간(미측정, X5) |
|
||||
| 최소 개선 방향 | 정적 빌드가 이미 있고 입력이 같으면(빌드 표식 파일에 트리 해시) 다시 빌드하지 않는다. 또는 FE-GATE-008이 `build:storybook`을 한 번 부르고 두 설정은 serve만 한다 |
|
||||
| 완료 기준 | FE-GATE-008 로그에 Storybook 빌드가 한 번이고 두 spec이 통과한다 |
|
||||
| RED 시험 | 적용 제외. 시간 개선이라 실행 기록(로그 줄 수)으로 본다 |
|
||||
|
||||
### PF-09 [w2-fe-2 파일] 쓰지 않는 devDependency `dependency-cruiser`
|
||||
|
||||
| 칸 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함(이월 0929/12-05, 남음) |
|
||||
| 관점 | 16 의존성, 9 유지보수 |
|
||||
| 심각도·우선순위 | Low·P3 |
|
||||
| 통제 | M0(쓰지 않는 의존성 검사가 없다) |
|
||||
| 증거 | E1 |
|
||||
| 근거 | `package.json:157` `"dependency-cruiser": "18.1.0"`. 실행하거나 import하는 코드가 없다(`git grep`: 주석 `scripts/check-architecture.ts:104`, `scripts/contracts/release-artifacts.ts:1024`과 "실행하지 않는다" 단언 `tests/unit/architecture-report.test.ts:65`뿐). 나머지 dependencies·devDependencies 27개는 모두 코드·설정·script나 peer 관계(`@babel/core` ← `@babel/eslint-parser`, `tailwindcss` ← `@tailwindcss/vite`, `@vitest/coverage-v8` ← `vitest.config.ts:57`)로 쓰인다 |
|
||||
| 영향 | 설치 시간, lockfile 직접 의존 18개, 공급망 기준선·SBOM 대상. dist에는 들어가지 않는다 |
|
||||
| 최소 개선 방향 | 빼고 lockfile·`config/security/dependency-baseline.json`을 다시 만든다(w2-fe-2가 이 줄을 다루는 중) |
|
||||
| 완료 기준 | `package.json`·lockfile에 없고 FE-GATE-001·010·013 뒤 명령이 통과한다 |
|
||||
| RED 시험 | 적용 제외. 쓰지 않는 의존성 검사(예: devDependency마다 참조 1곳 이상)를 두면 그 검사가 지금 실패한다 |
|
||||
|
||||
## 3. 넘길 것
|
||||
|
||||
- → **소유자(결정, D9 재검토 근거)**: D9의 전제였던 드릴 205,465 B(`performance-evidence.md:56`)가 바뀌었다. 지금 드릴은 201,870 B, 23 파일이다(`FE-GATE-020.txt:87`). D9 규칙(드릴 + 1 KiB를 KiB로 올림)의 값은 199 KiB = 203,776 B다. 예산 206,848 B보다 3,072 B 작다. 되돌림 규칙("204,800 B 이하이면 내린다", `:60-62`)의 조건은 이미 맞지만 "다시 볼 때" 조건 밖이라 아무것도 실패하지 않는다. 문서의 "드릴 위의 여유 1,383 B"(`:57-59`)도 지금은 약 4,978 B다. 초기 파일 상한 32도 지금 17이다. 예산을 내릴지 정한다(`decisions.md` 1절 4: 전제가 틀렸다는 새 증거).
|
||||
- → **소유자(결정 D1, zod·react-router advisory)**: 지금 여유 12,445 B면 zod 갱신(+약 7 KB)은 기능 0개 상태에는 들어간다. 첫 기능(6,327 B)과 함께는 13,327 B라 넘는다. PF-04의 vendor 그룹은 이 비용 판단과 별개다.
|
||||
- → **fe-design-system**: PF-03의 유틸리티가 `@layer utilities`에 있다. 그래서 `@layer components`의 같은 이름 class(`.container` `.hidden` `.table` `.grid` `.border` `.collapse` 등)를 이긴다. 제품 컴포넌트가 그 이름을 쓰면 docs 낱말 하나로 스타일이 바뀐다. `source("../../")`와 `source(none)` 중 어느 계약인지 정한다.
|
||||
- → **fe-react·fe-structure**: PF-01 (나)안이 `application.features.get` 보장을 라우트 단위로 옮겨도 되는지.
|
||||
- → **시험 구조(L 시험 담당) / [w2-fe-2 파일] `config/ci/gates.json`**: FE-GATE-005가 `test:unit`·`test:contract`를 돌린 뒤 `test:coverage`가 `tests/unit`·`tests/contract`를 다시 돈다. 빌드하는 시험(feature-shape-growth 4회 빌드, build-environment-bundle 2회 등)도 두 번 돈다(`FE-GATE-005.txt:151`·`:384`). 이 렌즈의 "같은 빌드 여러 번"에 걸리지만 시험 구조 몫이다.
|
||||
- → **시험 구조**: 시험 환경 분기가 제품 코드에 있다. `app-router.tsx:195` `!navigator.userAgent.toLowerCase().includes("jsdom")`이 dist boot 청크에 들어간다. 수십 B라 성능 영향은 없다.
|
||||
|
||||
## 4. 실험 요청
|
||||
|
||||
모두 desktop, 잠금 아래, 실험마다 작업 폴더를 되돌린다. 노트북 측정은 쓰지 않는다.
|
||||
|
||||
**X1 (PF-03) docs 낱말이 CSS를 바꾸는지, 범위를 좁히면 사라지는지** — 상한 15분
|
||||
```bash
|
||||
scripts/verify.sh exec -- bash -c '
|
||||
corepack pnpm build >/dev/null; A=$(ls dist/assets/*.css); echo "A=$A underline=$(grep -c "\.underline{" $A)"
|
||||
printf "\nunderline\n" >> docs/README.md
|
||||
corepack pnpm build >/dev/null; B=$(ls dist/assets/*.css); echo "B=$B underline=$(grep -c "\.underline{" $B)"
|
||||
git checkout -- docs/README.md
|
||||
sed -i "1s|.*|@import \"tailwindcss\" source(\"../../\");|" src/presentation/styles/theme.css
|
||||
corepack pnpm build >/dev/null; C=$(ls dist/assets/*.css)
|
||||
python3 -c "import sys,gzip,re;t=open(sys.argv[1]).read();i=t.find(\"@layer utilities{\");print(\"C gzip\",len(gzip.compress(t.encode(),6)));print(re.findall(r\"\}(\.[^{]+)\{\",t[i:i+4000])[:60])" "$C"
|
||||
corepack pnpm test:visual; echo visual_rc=$?
|
||||
git checkout -- src/presentation/styles/theme.css'
|
||||
```
|
||||
기대: A와 B 파일 이름이 다르고 B에 `.underline`이 있다. C에는 `.shadow\/canary`가 없다. visual_rc=0.
|
||||
|
||||
**X2 (PF-01) 한 context 두 기능에서 첫 화면이 다른 기능 실행부를 기다리는지** — 상한 10분. 패치(새 파일, 실험 뒤 지움):
|
||||
```diff
|
||||
--- /dev/null
|
||||
+++ b/tests/e2e/context-entry-probe.spec.ts
|
||||
@@ -0,0 +1,44 @@
|
||||
+import { spawnSync } from "node:child_process";
|
||||
+import { readFileSync } from "node:fs";
|
||||
+import path from "node:path";
|
||||
+import { expect, test } from "@playwright/test";
|
||||
+import { KO_MESSAGES } from "../../src/presentation/i18n/catalog.ts";
|
||||
+import { addGeneratedFeature, generatedFeature, routePath } from "../../scripts/lib/generated-feature.ts";
|
||||
+import { prepareFixtureBuilds, removeFixtureBuilds, type FixtureBuilds } from "./support/fixture-builds.ts";
|
||||
+import { startBuildServer } from "./support/service-worker-builds.ts";
|
||||
+
|
||||
+let builds: FixtureBuilds<"a"> | undefined;
|
||||
+let server: Awaited<ReturnType<typeof startBuildServer>> | undefined;
|
||||
+
|
||||
+test.beforeAll(async () => {
|
||||
+ test.setTimeout(300_000);
|
||||
+ builds = await prepareFixtureBuilds("context-entry-probe", [{ name: "a", edit: async (root) => {
|
||||
+ await addGeneratedFeature(root);
|
||||
+ const run = spawnSync(process.execPath, ["scripts/create-feature.ts", "beta-feature", "--context", "order-context"], { cwd: root, encoding: "utf8" });
|
||||
+ if (run.status !== 0) throw new Error(run.stdout + run.stderr);
|
||||
+ } }]);
|
||||
+ server = await startBuildServer({ a: builds.dist.a, b: builds.dist.a });
|
||||
+});
|
||||
+test.afterAll(async () => { await server?.close(); await removeFixtureBuilds(builds); });
|
||||
+
|
||||
+test("a context route draws without waiting for another feature's runtime", async ({ page }) => {
|
||||
+ const manifest = JSON.parse(readFileSync(path.join(builds!.dist.a, ".vite/manifest.json"), "utf8")) as Record<string, { file: string }>;
|
||||
+ const beta = manifest["src/features/beta-feature/feature-runtime.ts"]!.file;
|
||||
+ const requested: string[] = [];
|
||||
+ page.on("request", (request) => requested.push(`${Date.now()} ${new URL(request.url()).pathname}`));
|
||||
+ await page.route(`**/${beta}`, async (route) => { await new Promise((r) => setTimeout(r, 3_000)); await route.continue(); });
|
||||
+ const feature = generatedFeature(builds!.root);
|
||||
+ const started = Date.now();
|
||||
+ await page.goto(`${server!.origin}${routePath(feature.list)}`);
|
||||
+ await expect(page.getByRole("heading", { level: 1 })).toHaveText(KO_MESSAGES["route.auth.required.title"], { timeout: 15_000 });
|
||||
+ const elapsed = Date.now() - started;
|
||||
+ console.log(JSON.stringify({ elapsed, beta, requested }, null, 1));
|
||||
+ expect(elapsed).toBeLessThan(3_000);
|
||||
+});
|
||||
```
|
||||
명령: `scripts/verify.sh exec -- corepack pnpm exec playwright test tests/e2e/context-entry-probe.spec.ts --project=chromium`. 기대(지금): 실패, `elapsed` ≥ 3000. 출력의 요청 순서에서 beta 실행부가 목록 페이지 청크보다 먼저 끝나는지 본다. context ID가 `order-context`가 아니면 `create:feature order-feature` 출력의 context로 바꾼다.
|
||||
|
||||
**X3 (PF-02) SW ACTIVE + 생성 기능 24·25개 빌드** — 상한 20분
|
||||
```bash
|
||||
scripts/verify.sh exec -- bash -c '
|
||||
python3 - <<"PY"
|
||||
p="src/features/product-capabilities.ts"; s=open(p).read()
|
||||
s=s.replace("const SERVICE_WORKER: InstalledServiceWorkerSelection | null = null;",
|
||||
"const SERVICE_WORKER: InstalledServiceWorkerSelection | null = { mode: \"ACTIVE\", scriptPath: \"service-worker.js\", handlers: [\"PWA_STATIC_ASSETS\"] };")
|
||||
open(p,"w").write(s)
|
||||
PY
|
||||
corepack pnpm create:feature f1 --with-create --keyed >/dev/null || exit 3
|
||||
for i in $(seq 2 20); do corepack pnpm create:feature f$i --context f1-context --with-create --keyed >/dev/null || exit 3; done
|
||||
corepack pnpm create:feature f21 --with-create --keyed >/dev/null || exit 3
|
||||
for i in 22 23 24; do corepack pnpm create:feature f$i --context f21-context --with-create --keyed >/dev/null || exit 3; done
|
||||
corepack pnpm build > /tmp/x3-24.log 2>&1; echo "24 rc=$? assets=$(ls dist/assets | grep -cE "\.(js|css)$")"
|
||||
corepack pnpm create:feature f25 --context f21-context --with-create --keyed >/dev/null || exit 3
|
||||
corepack pnpm build > /tmp/x3-25.log 2>&1; echo "25 rc=$? assets=$(ls dist/assets | grep -cE "\.(js|css)$")"; grep -n "Static asset" /tmp/x3-25.log'
|
||||
```
|
||||
기대: 24 rc=0(자산 ≤256), 25 rc≠0과 `Static asset count exceeds its bound.`. 경계가 다르면 그 기능 수와 자산 수를 적는다.
|
||||
|
||||
**X4 (PF-04) build id만 다른 두 빌드에서 이름이 바뀌는 초기 JS** — 상한 10분
|
||||
```bash
|
||||
scripts/verify.sh exec -- bash -c '
|
||||
sha=$(git rev-parse HEAD)
|
||||
run() { VITE_BUILD_ID=$1 VITE_COMMIT_SHA=$sha RELEASE_ID=probe corepack pnpm build >/dev/null && corepack pnpm check:bundle >/dev/null && cp artifacts/performance/bundle.json /tmp/x4-$2.json; }
|
||||
run probe-101-1 a0 && run probe-102-1 b0
|
||||
corepack pnpm create:feature order-feature --with-create --keyed >/dev/null
|
||||
run probe-101-1 a1 && run probe-102-1 b1
|
||||
for n in 0 1; do python3 - /tmp/x4-a$n.json /tmp/x4-b$n.json $n <<"PY"
|
||||
import json,sys
|
||||
a,b=(json.load(open(f)) for f in sys.argv[1:3])
|
||||
gz={o["path"].removeprefix("dist/"):o["gzipBytes"] for o in a["outputs"]}
|
||||
bs=set(b["classification"]["initialFiles"])
|
||||
ren=[f for f in a["classification"]["initialFiles"] if f not in bs]
|
||||
print(sys.argv[3],"features renamed",ren,sum(gz[f] for f in ren),"of",a["measurements"]["initialJsGzipBytes"])
|
||||
PY
|
||||
done'
|
||||
```
|
||||
기대(지금): 기능 0개는 약 82,915 B(42.7%), 기능 1개는 더 작다. 문서 값 44,297 B와 비교한다.
|
||||
|
||||
**X5 (PF-08, 선택) Storybook 빌드 한 번의 시간** — 상한 5분: `scripts/verify.sh exec -- bash -c 'time corepack pnpm build:storybook >/dev/null'`
|
||||
|
||||
**X6 (PF-07, 선택)** boot modulepreload를 넣은 빌드와 지금 빌드를 같은 세션에서 `test:performance --runs=5`로 번갈아 잰다. 패치는 고치는 쪽이 만든다. 고칠지 정한 뒤에만 돌린다.
|
||||
|
||||
## 5. 결함 아님으로 판정한 의심
|
||||
|
||||
- 기준선과 지금 빌드의 차이 49 B: build id 차이 범위다. 허용 256 B 안이고 FE-GATE-005가 통과했다.
|
||||
- 예산 206,848 B가 기준선보다 12,445 B 넉넉함: D9의 "다시 볼 때" 조건이 아직 오지 않았다. 결정 사항이라 3절로 넘겼다.
|
||||
- `initialJsFiles` 32 대 지금 17: 상한을 정한 근거(`performance-evidence.md:222-229`)대로다. 결정 몫이다.
|
||||
- 초기 파일 17개로 나뉨: HTTP/2 전제와 측정이 문서에 있다(`performance-evidence.md` 「초기 청크 수와 HTTP/1.1」).
|
||||
- 25개 기능에서 초기 JS 211,739 B로 예산 초과(`feature-shape-growth.json`): 기록이 공식(예산−기준선−첫 기능)/기능당으로 예고한다(`feature-shape-ceilings.json:26`).
|
||||
- config.json → release-manifest.json 직렬 fetch: manifest URL이 런타임 설정 값이라(`src/contracts/env.ts:66`) 순서가 필요하다.
|
||||
- `dist/.vite/manifest.json`(6.3 KB)이 dist에 남음: `assetManifestHash`와 release 검사가 이 파일을 읽는다. 브라우저는 요청하지 않는다. module inventory는 빌드 뒤 dist에서 빼서 `artifacts/`로 옮긴다(`generate-build-manifest.ts:122-129`).
|
||||
- `runtime-config.schema.json`이 dist에 있음: 운영 산출물로 계약에 있다. SW precache에서도 뺀다(`generate-service-worker-assets.ts:47`).
|
||||
- `fileserver-upload.ts`·`cursor-pagination-runtime.ts`·`service-worker-lifecycle.ts`·`service-worker-static-assets.ts`가 boot 청크의 module 목록에 있음: 코드는 tree-shake로 빠졌다(`/v1/files`, `PAGINATION_ABORTED`, `STATIC_INSTALL_REJECTED` 0건).
|
||||
- zod `toJSONSchema` 코드가 boot에 있음: zod classic이 schema마다 메서드를 붙이는 패키지 구조다. 갱신·교체는 D1 결정과 묶인다.
|
||||
- SW install에서 `skipWaiting()` 없음, `clients.claim()` 없음, 캐시 이름은 자산 묶음 digest, 활성화 때 현재와 이전 하나만 남김: 렌즈 함정 10대로다(`service-worker-entry.ts:82-90`, `service-worker-lifecycle.ts:152-200`).
|
||||
- 청크 실패 reload: marker TTL 안에 한 번만이다(`decide-chunk-recovery.ts:39-56`).
|
||||
- boot JSON fetch `cache: "no-store"`(`read-bounded-boot-json.ts:87`), cache-policy의 index `no-cache`·config/manifest `no-store`·`/assets/*` `immutable`·sourcemap 비공개: 함정 12대로다.
|
||||
- hosting probe가 CSS의 `Cache-Control`을 따로 보지 않음: `/assets/*` pathPattern 하나로 선언하고, CSS의 content-type은 따로 본다(`hosting-probe.ts:300-345`). 경로 단위 설정이라 표본 하나로 충분하다고 본다.
|
||||
- 앱 빌드가 FE-GATE-008 안에서 두 번(e2e, visual): identity가 다르다(`playwright.visual.config.ts:73-79`). 같은 빌드가 아니다.
|
||||
- 폰트·이미지 크기: 둘 다 없다.
|
||||
- 쓰지 않는 의존성: `dependency-cruiser` 하나뿐이다(PF-09). `msw`는 시험과 생성 시험 템플릿에서 쓴다. `@babel/core`·`tailwindcss`는 peer다.
|
||||
- 문서·주석·리뷰어 대상 지시문: 읽은 파일에서 찾지 못했다.
|
||||
@@ -0,0 +1,205 @@
|
||||
# round9 L7 보안 리뷰 (렌즈 fe-security) — 대상 `5250ff95`
|
||||
|
||||
> round9 리뷰(2026-11-12, 대상 main `5250ff95`)의 영역 기록이다. 서브에이전트가 쓴 원문을 그대로 옮겼다. 바꾼 것은 이 인용 블록과, 작업 폴더 절대 경로를 `(작업 폴더)`로 줄인 것뿐이다. 발견 ID는 이 파일의 이름표(R-01 등)이고, 라운드 ID(`1112/NN-MM`)와의 대응은 [README](2026-11-round9-review.md) 15절이다.
|
||||
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- 판정: **고칠 것 있음.** 새 발견 3건(Medium·P2 1, Low·P3 2). Critical·High·P1 없음.
|
||||
- 핵심은 SEC-01이다. 짝 Fileserver 업로드 client(`createFileserverUploadClient`)는 템플릿의 자격 증명 경로 밖에 있다. 그래서 업로드의 서버 401이 세션에도 `onCredentialRejected`에도 가지 않는다. 매뉴얼 예제 주석은 "그 401은 세션을 로그아웃시킨다"고 적는다. 또 JWT 모드(짝 백엔드 기본값)에서는 업로드에 세션 bearer를 붙이는 지원 경로가 없다.
|
||||
- 나머지 둘은 낡은 설정 한 덩이(`minimumReleaseAgeExclude`)와, 실제보다 좁게 적은 secret scan 범위 설명이다.
|
||||
- XSS(raw HTML·script URL·`href`), CSP·보안 헤더 선언, V3 실행기의 401·자격 증명 헤더, token 저장 금지, Cache Storage·SW 캐시의 개인 데이터, 오류 원문 노출, lockfile·기준선은 렌즈 기준을 지킨다(5절).
|
||||
- advisory D1(zod 4.4.3·react-router-dom 7.18.1)은 그대로 결정 대기다(`package.json:135-136`). 다시 올리지 않는다.
|
||||
|
||||
## 1. 범위
|
||||
|
||||
### 1.1 읽은 경로
|
||||
|
||||
- 렌즈: `.claude/skills/fe-security/SKILL.md`. 리뷰어 정의 `.claude/agents/reviewer.md`, `docs/work/reference/review-criteria.md`, `decisions.md`, `defect-patterns.md`, `docs/work/experts.md`.
|
||||
- `bbde570..5250ff95` 변경(범위 안): `config/security/secret-scan-policy.json`(루트 셋 삭제·문구 번역), `docs/security/browser-boundary.md`·`supply-chain.md`(한국어로 옮김), `eslint.config.ts`(문구 ignore 한 줄), `package.json`(타입 검사 스크립트 정리, 의존성 변경 없음), `scripts/scan-dependency-advisories.ts`(주석), `src/adapters/http/backend-envelope.ts`·`fileserver-upload.ts`(성공 Envelope의 `traceId`). lockfile·기준선은 바뀌지 않았다(`pnpm-lock.yaml` sha256 = 기준선 `lockfileSha256` `3a818cf0…`).
|
||||
- 바뀌지 않은 곳도 읽었다:
|
||||
- `src/adapters/auth/**` 전부
|
||||
- `src/adapters/http/**`: V3 실행기의 자격 증명·401·redirect·final invariant 부분, `http-contract-bridge.ts`의 `admitCredentialHeaders`·`projectRequest`, `backend-envelope.ts`, `fileserver-upload.ts` 전부
|
||||
- `src/adapters/storage/**`: `browser-storage-adapter.ts`·codec 전부, IndexedDB·OPFS는 LOGOUT·ACCOUNT_DELETION 정책 판정과 proof 정규식
|
||||
- `src/adapters/service-worker/**`: entry, 정적 자산 캐시 조건
|
||||
- `src/presentation/security/safe-text.tsx`, `index.html`, `config/hosting/security-headers.json`·`cache-policy.json`
|
||||
- `config/security/**` 전부, `recipes/session-owners/**` 전부
|
||||
- `package.json`·`pnpm-workspace.yaml`·`.npmrc`·`renovate.json`
|
||||
- 경로를 따라 더 읽은 곳(판정 근거로만):
|
||||
- `src/bootstrap/runtime-adapters.ts`의 `attachCredentials`·`reportServerUnauthenticated`, `product-composition-contract.ts`, `product-session-owner-context.ts`, `session-owner-fetch.ts`
|
||||
- `src/contracts/storage-keys.ts`·`rest-profiles.ts`, `src/adapters/cache-storage/public-cache-response-validation.ts`
|
||||
- `scripts/security-scan.ts`, `scripts/lib/secret-scan-evaluator.ts`·`repository-file-inventory.ts`, `scripts/check-browser-security.ts`, `scripts/verify-hosting-headers.ts`, `tests/e2e/production-csp.spec.ts`
|
||||
- `docs/manual/02-decision-tables.md` 5·7절, `docs/manual/04-paired-backend-session.md`, `docs/architecture/optional-adapter-recipes.md` 4절 9번
|
||||
- 짝 백엔드 `SecurityConfig.java`(`/v1/files`가 인증을 요구하는지만)
|
||||
|
||||
### 1.2 렌즈 기준으로 본 것
|
||||
|
||||
- 함정 1(raw HTML): `src`·`recipes`에 `innerHTML`·`outerHTML`·`insertAdjacentHTML`·`srcdoc`·`dangerouslySetInnerHTML`·`eval`·`new Function`·`javascript:`가 0건이다(`src/contracts/zod.ts` 주석 1건만). lint 셀렉터는 `**/*.{ts,tsx,mts,cts}` 전부에 걸린다. 이 목록을 덮어쓰는 블록은 하나뿐이다. 그 블록도 보안 셀렉터를 다시 넣는다(`eslint.config.ts:515-527`, `:919-922`).
|
||||
- 함정 2·3(CSP): `security-headers.json:4`가 `unsafe-*` 없이 `script-src 'self'`·`style-src 'self'`다. e2e가 그 헤더로 부팅한다(`production-csp.spec.ts:10-73`). `connect-src https:`의 한계는 문서에 있다. `blob:`·CDN·`wss:`를 넓히는 방법은 recipe 9번에 있다.
|
||||
- 함정 4(token 저장): `AUTH_TOKEN`은 `forbidden`이다. `getStorageDefinition`이 `sensitive-forbidden`·`external`을 거절한다(`storage-keys.ts:124-135`, `:208-221`). OIDC recipe는 token을 메모리에만 둔다. sessionStorage에는 PKCE 거래 하나만 10분 동안 둔다.
|
||||
- 함정 5(자격 증명 헤더): 두 번 거른다. `validateCredentialPatch`(`external-session-adapter.ts:42-67`)와 `admitCredentialHeaders`(`http-contract-bridge.ts:66-106`)다.
|
||||
- 함정 6(401): V3는 401에서 끝나고 다시 보내지 않는다(`http-execution-v3.ts:792-793`). 401은 자격 증명을 낸 쪽에만 간다(`runtime-adapters.ts:605-623`, `:675-680`). 업로드 경로는 SEC-01.
|
||||
- 함정 8(오류 원문): 서버 `error.message`는 어디에도 실리지 않는다. 필드 오류는 path·code만 남는다(`errors.ts:290-318`).
|
||||
- 함정 9(비밀 값): 설정 키 이름 금지 조각과 `.env.example` 경고가 있다. secret scan 범위 설명은 SEC-03.
|
||||
- 함정 10(source map): `vite.config.ts:213` `sourcemap: false`, `check-browser-security.ts:35-45`.
|
||||
- 함정 12(의존성): 직접 의존성 35 = 기준선. integrity는 562개로 lockfile 행 수와 같다. git·tarball URL은 0건이다. 예외(`vulnerability-exceptions.json`)는 비었다. 낡은 release-age 예외는 SEC-02.
|
||||
- 함정 13(브라우저 저장소): 기본 조립에는 IndexedDB·OPFS가 없다(`AVAILABLE_NOT_COMPOSED`). Cache Storage adapter는 `private`·`set-cookie`·`Vary: authorization|cookie`를 거절하고 `credentials: "omit"`로 받는다(`public-cache-response-validation.ts:47-62`, `:189-190`, `:232`). SW는 같은 출처의 검증된 정적 자산만 캐시한다(`service-worker-entry.ts:102-109`).
|
||||
- 체크리스트:
|
||||
- 로그인 복귀 주소: OIDC는 같은 출처 경로만 받는다(`oidc-pkce-session-owner.ts:174-186`).
|
||||
- `postMessage`: SW·BroadcastChannel·worker·storage 이벤트만 있고 모두 같은 출처다.
|
||||
- 데모 credential: VD-23 결정이다. 운영 대상에서는 부팅과 admission이 거절한다(5절).
|
||||
|
||||
### 1.3 게이트 실행 결과(읽기만)
|
||||
|
||||
- `desktop:/tmp/claude-gates/r9fe-base/summary.txt`: tree `75cc3752` = `5250ff95`, CI env.
|
||||
- FE-GATE-001~012는 모두 rc=0이다(008 e2e에 `production-csp.spec.ts` 포함).
|
||||
- **FE-GATE-013은 rc=1(2초)이다.** 로그는 `FE-GATE-013 security: FAIL` 한 줄뿐이다. 사전 점검(user namespace)에서 멈춘 것으로 보이지만, 로그로 확인하지 못했다.
|
||||
- FE-GATE-020은 읽은 시점에 아직 돌고 있었다.
|
||||
- 그래서 secret scan(`build:release-candidate` 안)과 `check:browser-security`는 이번 실행에서 돌았는지 모른다. D8 판정에 필요한 `parts`를 EXP-L7-01로 낸다.
|
||||
|
||||
### 1.4 확인 못 한 것
|
||||
|
||||
- FE-GATE-013의 뒤 명령 4개 rc(EXP-L7-01).
|
||||
- 실제 Keycloak·Redis session 백엔드에 붙인 업로드 401 동작. MSW·코드로만 봤다.
|
||||
- advisory의 지금 목록. FE-GATE-027은 release 단계라 이번 실행에 없다.
|
||||
- 운영 호스트의 실제 응답 헤더(FE-GATE-019, production 단계).
|
||||
- IndexedDB·OPFS 런타임 9천 줄의 세부 경로. 정책 판정, proof, 경로 토큰 정규식만 봤다. 지난 라운드 05 영역의 몫이다.
|
||||
|
||||
### 1.5 지난 발견 중 이 범위에 걸린 것의 지금 상태
|
||||
|
||||
| ID | 지금 상태 | 근거 |
|
||||
| --- | --- | --- |
|
||||
| 1103/13-03 (D1) | 결정 대기 그대로 | `package.json:135-136` zod 4.4.3, react-router-dom 7.18.1 |
|
||||
| 0929/05-06 | 남음 | proof 정규식 `{16,128}`(`indexeddb-runtime.ts:97`) 대 `{16,512}`(`opfs-byte-store-adapter.ts:1930`) |
|
||||
| 0929/08-08 | 남음(포트 쪽) | `auth-session-port.ts:38` `beginSignIn(returnTo?)`에 뜻이 없다. OIDC recipe는 라우터 기준 경로로 읽는다(`oidc-pkce-session-owner.ts:491`, `${basePath}${returnTo}`). `session-provider.tsx:99`가 라우터 `pathname`을 넘기므로 recipe끼리는 맞는다 |
|
||||
| 0929/13-04 | 일부 | CSP 문자열 사본은 `tests/fixtures/hosting/response-headers.json` 4곳만 남았다. e2e는 정본 파일을 읽는다. fixture 모드의 `verify:hosting-headers`가 선언과 문자 그대로 비교한다(`verify-hosting-headers.ts:174-183`) |
|
||||
|
||||
## 2. 발견
|
||||
|
||||
### SEC-01 업로드 client의 서버 401이 세션에 닿지 않고, JWT 모드에는 업로드 자격 증명의 지원 경로가 없다
|
||||
|
||||
- 성격: 확인된 결함(매뉴얼 예제의 약속과 코드가 다르다). JWT 부분은 구조적 위험이다.
|
||||
- 관련 관점: 15, 6, 17, 23
|
||||
- 심각도·우선순위: **Medium·P2**
|
||||
- 위험한 경로가 남았지만 V3 operation 경로는 막혀 있다. 업로드를 조립한 제품에서만 닿는다.
|
||||
- 쓰지 못하게 막지는 않는다. 다음 V3 요청의 401이 세션을 내린다.
|
||||
- 다운스트림은 매뉴얼 예제를 그대로 복제한다.
|
||||
- 통제: 업로드 경로는 M0다. 401을 알리는 수단이 없음을 코드로 확인했다. V3 경로는 M2다.
|
||||
- 증거: E1
|
||||
- 근거:
|
||||
- `src/adapters/http/fileserver-upload.ts:700-704`, `:707-755`: 401 Envelope은 `kindForStatus` → `AUTH_REQUIRED` 실패로 돌아갈 뿐이다. 누구에게도 알리지 않는다. `FileserverUploadClientDependencies`(`:132-158`)에 그런 hook이 없다.
|
||||
- `tests/integration/fileserver-upload.test.ts:367`이 401 → `AUTH_REQUIRED`만 고정한다.
|
||||
- `src/bootstrap/runtime-adapters.ts:605-623`, `:675-680`: 401을 세션이나 `onCredentialRejected`로 보내는 곳은 V3 `contractOperations.execute` 안뿐이다.
|
||||
- 같은 파일 `:730-731`: 업로드 capability(`product.capabilities`)는 감싸지 않고 기능에 그대로 넘긴다.
|
||||
- `docs/manual/02-decision-tables.md:486-493`: 업로드 조립 예제다. 같은 `BACKEND_SESSION` provider를 업로드와 `credentialProviders`에 함께 주고, `// BACKEND_SESSION은 세션 쿠키 그 자체다. 그 401은 세션을 로그아웃시킨다(5절).`라고 적는다.
|
||||
- `docs/manual/04-paired-backend-session.md:191`: 401이 세션에 닿지 않으면 "화면은 로그인 상태로 남고, 요청마다 `AUTH_REQUIRED` 실패 화면만 보인다"고 적는다.
|
||||
- `src/bootstrap/product-composition-contract.ts:80-101`: `ProductCompositionContext`에는 세션 자격 증명(템플릿 `attachCredentials`)이 없다. 그래서 JWT 모드(`EXTERNAL_BEARER`)의 업로드에 bearer를 붙이려면, 제품이 `composeProductSessionOwner`의 owner를 모듈 변수로 붙잡아 직접 불러야 한다. 이 방법은 문서에 없고, 템플릿의 scope fence·세션 상태 검사(`runtime-adapters.ts:540-596`)를 건너뛴다.
|
||||
- 매뉴얼 02 7절에는 JWT 모드 업로드 안내가 없다.
|
||||
- 짝 백엔드 `SecurityConfig.java:100`은 `anyRequest().authenticated()`이고 `/v1/files`는 공개 경로가 아니다.
|
||||
- 발생 조건:
|
||||
1. 제품이 매뉴얼 02 7절대로 Fileserver 업로드를 조립했다.
|
||||
2. 업로드 직전에 서버 세션이 끝났다. Redis TTL 만료, 다른 탭이나 서버에서 로그아웃, OIDC access token 거부가 그런 경우다.
|
||||
- JWT 모드는 조립 단계부터 해당한다.
|
||||
- 영향:
|
||||
- 업로드는 `AUTH_REQUIRED`로 실패한다. 세션은 `authenticated`로 남는다. 서버 상태 fence도, OIDC의 401 뒤 refresh(`notifyUnauthenticated`)도 일어나지 않는다.
|
||||
- 화면은 로그인 상태인데 업로드만 계속 실패한다.
|
||||
- JWT 모드에서 제품이 owner를 직접 부르면, 로그아웃·계정 전환 fence 밖에서 bearer를 얻는다. 이 부분은 추론이다.
|
||||
- 최소 개선 방향(공개 계약을 바꾸므로 소유자 확인):
|
||||
- (a) 템플릿이 업로드 capability의 `attachCredentials`를 감싼다. 401을 받으면 V3와 같은 판정(`reportServerUnauthenticated`)을 부르게 한다.
|
||||
- 또는 (b) `FileserverUploadClientDependencies`에 선택 `onUnauthenticated()`를 더하고, 매뉴얼 예제가 `context.notifySessionUnauthenticated`를 넘긴다.
|
||||
- 두 경우 모두 `ProductCompositionContext`에 세션 자격 증명을 내주는 함수(템플릿 `attachCredentials`와 같은 scope·세션 검사)를 더한다. 매뉴얼 02 7절에 JWT 모드 조립을 적는다.
|
||||
- 권하는 안은 (a)다. 제품 코드가 401 처리를 빠뜨릴 수 없다.
|
||||
- 완료 기준:
|
||||
- 업로드의 서버 401이 V3와 같은 규칙으로 간다. 템플릿 세션 자격 증명이면 세션이 `unauthenticated`가 되고, 제품 provider면 `onCredentialRejected`가 불린다.
|
||||
- JWT 모드 업로드가 문서의 조립만으로 세션 bearer를 붙인다. scope가 READY가 아니면 보내지 않는다.
|
||||
- 매뉴얼 02 7절 주석이 동작과 같다.
|
||||
- RED 시험 아이디어:
|
||||
- `tests/unit/runtime-adapters-credential-order.test.ts`와 같은 조립 fixture를 쓴다. 제품이 `fileserverUpload` capability와 `onCredentialRejected` spy를 돌려준다.
|
||||
- 기능 쪽에서 `createFileserverUploadClient(capability).upload()`를 부르고, MSW가 `POST /v1/files`에 401 `UNAUTHENTICATED` Envelope으로 답한다.
|
||||
- spy 호출 1회(또는 세션 상태 `unauthenticated`)를 기대한다. 지금은 0회라 실패한다.
|
||||
- JWT 쪽: `EXTERNAL_BEARER` 프로필로 조립한 업로드가 세션 owner의 `authorization`을 싣는다. scope FENCED에서는 fetch 0회여야 한다. 지금은 조립할 수단이 없어 테스트를 쓸 수 없다. 이것이 RED다.
|
||||
|
||||
### SEC-02 `minimumReleaseAgeExclude`의 네 줄이 스스로 적은 재검토 조건을 넘겼다
|
||||
|
||||
- 성격: 확인된 결함(설정 주석의 약속 위반, 낡은 설정)
|
||||
- 관련 관점: 16, 9
|
||||
- 심각도·우선순위: **Low·P3**. 정확한 버전만 빼므로 보안 피해는 없다.
|
||||
- 통제: M1(주석 규칙만)
|
||||
- 증거: E1
|
||||
- 근거:
|
||||
- `pnpm-workspace.yaml:9-18`: 2026-07-25에 추가한 `@playwright/test@1.62.0`, `playwright-core@1.62.0`, `playwright@1.62.0`, `eslint@10.8.0`. 주석은 "remove an entry when its version is bumped or is older than the configured minimum release age"라고 적는다.
|
||||
- 설정한 최소 나이는 pnpm 기본 1일이다. `renovate.json:7`이 "a release must be a day old, the pnpm minimumReleaseAge default"라고 적는다. pnpm 11.17.0 기본값은 `"minimum-release-age": 24 * 60`이다(노트북 corepack 캐시 `~/.cache/node/corepack/v1/pnpm/11.17.0/dist/pnpm.mjs:149201`).
|
||||
- 네 버전은 2026-11-12 기준 석 달 넘게 지났다.
|
||||
- 발생 조건: 항상.
|
||||
- 영향:
|
||||
- 예외 목록이 지금 필요한 예외처럼 읽힌다. 다음 사람이 비슷한 예외를 날짜 없이 더한다.
|
||||
- 기능 영향은 없다. pnpm 11은 frozen 설치에서도 lockfile을 release-age로 다시 검사하는데, 네 버전 모두 통과한다.
|
||||
- 최소 개선 방향:
|
||||
- 네 줄과 주석을 지운다.
|
||||
- 예외를 다시 둘 때는 항목마다 만료일을 적게 하고, 시험이 지난 만료일을 거절하게 한다.
|
||||
- 완료 기준: `minimumReleaseAgeExclude`가 없거나, 모든 항목에 지나지 않은 만료일이 있다.
|
||||
- RED 시험 아이디어: `tests/unit/pnpm-install-policy.test.ts`에 시험을 더한다. 각 예외 항목에 `# until YYYY-MM-DD` 표지가 있고 그 날짜가 오늘 이후인지 본다. 지금은 표지가 없어 실패한다. 줄을 지우면 빈 목록이라 통과한다.
|
||||
|
||||
### SEC-03 secret scan·공급망 목록의 "범위" 설명이 실제 검사 범위보다 좁다
|
||||
|
||||
- 성격: 확인된 결함(문서·설정 설명이 코드와 다르다. 코드가 맞다)
|
||||
- 관련 관점: 23, 9, 15
|
||||
- 심각도·우선순위: **Low·P3**. 실제 검사는 설명보다 넓어 보안 피해는 없다.
|
||||
- 통제: M3(검사 자체는 FE-GATE-013에서 돈다)
|
||||
- 증거: E1
|
||||
- 근거:
|
||||
- 설명:
|
||||
- `config/repository-layout.json:15`: `"secret-scan": "비밀값 검사와 공급망 목록의 범위. …trackedRoots가 이 집합과 같아야 한다"`
|
||||
- `docs/security/supply-chain.md:24-25`: "대상은 source, … 추적되는 config/schema, public 폴더, 빌드된 asset, 생성된 release metadata다"
|
||||
- `config/security/secret-scan-policy.json:3-34`: `trackedRoots` 31개에 `docs/`, `.claude/`, 루트 문서, `.env.example`, `renovate.json`이 없다.
|
||||
- 코드:
|
||||
- `scripts/lib/repository-file-inventory.ts:91`이 `git ls-files -z` 전부를 읽는다.
|
||||
- `:263-272`는 `trackedRoots`가 비어 있지 않은지만 본다.
|
||||
- `:322-326`이 추적 파일 전부와 생성 파일을 `files`로 돌려준다.
|
||||
- `scripts/lib/secret-scan-evaluator.ts:172-175`는 `includedPaths`가 없으면(`secret-scan-policy.ts:6`) 그 전부를 검사한다.
|
||||
- `scripts/generate-supply-chain.ts:202`의 source 집합도 추적 파일 전부다.
|
||||
- 발생 조건: 사람이 검사 범위를 문서·등록부로 판단할 때.
|
||||
- 영향:
|
||||
- "docs·`.env.example`은 검사하지 않는다"는 틀린 이해를 준다.
|
||||
- 설명에 맞춘다며 검사를 좁히는 변경이 나올 수 있다. 꼭 지킬 것 4(게이트 기준 낮추기 금지)에 걸린다.
|
||||
- 최소 개선 방향:
|
||||
- 설명을 코드에 맞춘다. 등록부 문구와 supply-chain 문단을 "추적되는 파일 전부 + `dist` + `artifacts/release`. `trackedRoots`는 비어 있으면 안 되는 루트"로 고친다.
|
||||
- 검사 범위는 줄이지 않는다.
|
||||
- 완료 기준: 등록부·문서·정책 필드 설명이 실제 검사 대상과 같다.
|
||||
- RED 시험 아이디어:
|
||||
- 코드가 맞으므로 코드 RED는 없다.
|
||||
- 대신 지키는 시험을 더한다. `evaluateSecretScan`에 `trackedRoots` 밖의 추적 파일(`docs/x.md`)을 넣어 발견이 나는지 고정한다. 지금도 통과한다. 범위를 좁히는 변경을 잡는다.
|
||||
|
||||
## 3. 넘길 것
|
||||
|
||||
- → fe-react·fe-structure: `docs/manual/02-decision-tables.md:467`의 업로드 예제가 `declare module "../features/feature-adapter-contribution.ts"`로 `FeaturePlatformCapabilities`를 보강한다. 매뉴얼 03(`03-outside-feature-folder.md:118-119`)과 recipe(`browser-file-session-capability.ts:26-31`)는 그 보강을 `check:types:node`가 보지 못하니 `src/features/product-capabilities.ts`의 `ProductFeaturePlatformCapabilities`에 적으라고 한다. 복사해 쓰는 예제가 서로 다르다. SEC-01을 고칠 때 같은 예제를 고친다.
|
||||
- → fe-react: 업로드 client에는 V3의 `scope.isCurrent()` 재확인이 없다(`fileserver-upload.ts:260-305`). 계정 전환 중에 시작한 업로드의 결과가 다음 세션에 도착할 수 있다(추론). HTTP·scope 흐름이라 그쪽 몫이다. SEC-01의 (a)안이면 함께 닫힌다.
|
||||
- → 총괄: FE-GATE-013 rc=1의 원인 줄이 로그에 없다(`FE-GATE-013.log` 한 줄). D8 판정은 EXP-L7-01로 한다.
|
||||
|
||||
## 4. 실험 요청
|
||||
|
||||
| ID | 목적 | 명령 | env | 시간 상한 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| EXP-L7-01 | D8 판정: FE-GATE-013 실패가 사전 점검 하나뿐이고 뒤 명령(`verify:reproducible-build`, `build:release-candidate` 안의 secret scan, `verify:local-evidence`, `check:browser-security`)이 rc=0인지 | `scripts/verify.sh parts FE-GATE-013` | `CI=true`와 workflow 빌드 식별 변수(merge 실행과 같게) | 20분 |
|
||||
| EXP-L7-02 | SEC-03 확인: 검사 파일에 `trackedRoots` 밖 파일이 드는지(빌드된 `dist`가 있는 상태, EXP-L7-01 뒤) | `scripts/verify.sh exec -- node --input-type=module -e "import {evaluateRepositorySecretScan} from './scripts/lib/secret-scan-evaluator.ts'; const e = await evaluateRepositorySecretScan({}); const out = e.scanFiles.filter((f) => f.startsWith('docs/') \|\| f.startsWith('.claude/') \|\| f === '.env.example' \|\| f === 'README.md'); console.log(e.scanFiles.length, out.length, out.slice(0, 5));"` | 없음 | 2분 |
|
||||
|
||||
- 기대: EXP-L7-02의 둘째 수가 0보다 크다(`docs/` 260여 개). 0이면 SEC-03을 거둔다.
|
||||
|
||||
## 5. 결함 아님으로 판정한 의심
|
||||
|
||||
- `DEMO_AUTHORIZATION_MARKER`가 운영 번들에 있다(`external-session-adapter.ts:118`). 데모 모드와 비밀 아닌 표지는 VD-23 결정이다(`docs/adr/VD-23-…md:326-329`). 비로컬에서는 부팅 스키마와 release admission이 `AUTH_MODE=demo`를 거절한다(`release-artifacts.ts:104-109`, `deployment-admission.ts:97-100`). 서버가 표지를 받지 않는다.
|
||||
- `LinkButton`·`Breadcrumbs`의 `href`는 scheme을 보지 않는다(`link-button.tsx:46`, `breadcrumbs.tsx:24`). 템플릿 안 호출은 고정값이다. `script-src 'self'`(no `unsafe-inline`)가 `javascript:` 실행을 막는다. 일반 primitive의 확장 지점이다.
|
||||
- `SafeText`의 소비자가 없다. 확장 지점이다(테스트·lint fixture는 있다).
|
||||
- IndexedDB·OPFS의 LOGOUT purge를 템플릿이 부르지 않는다. 두 런타임 모두 조립하지 않는 opt-in이다(`AVAILABLE_NOT_COMPOSED`).
|
||||
- `PERSONAL`·`CONFIDENTIAL`은 `OPAQUE_PARTITION`이어야 하고, 그 partition은 purge 정책이어야 한다. 정책 검증이 이를 강제한다(`shared.ts:274-283`).
|
||||
- 제품은 `scopeParticipants`(async 허용)로 부른다.
|
||||
- local-draft recipe가 계정을 가로질러 초안을 남긴다(`indexeddb-feature-capability.ts:39,58-66`). `INTERNAL` 분류에 `ORIGIN_SHARED`를 명시한 예제이고, 개인 분류는 정책이 막는다.
|
||||
- `connect-src 'self' https:`가 넓다. 한계와 좁히는 조건이 문서에 있다(`browser-boundary.md:21-25`). 생성기가 없는 것은 적힌 한계다.
|
||||
- `serviceWorker`·`hashedAsset` surface에 보안 헤더를 요구하지 않는다(`cache-policy.json:24-46`). 운영 조건 문서는 문서·JSON surface(3~5)에만 헤더를 약속한다(`release-cache-rollback.md:148-151`).
|
||||
- `allowBuilds: esbuild, msw`(`pnpm-workspace.yaml:6-8`). 게이트와 문서 설치는 늘 `--ignore-scripts`다. `msw.workerDirectory`가 없어 msw postinstall이 public에 worker를 쓰지 않는다.
|
||||
- OIDC recipe가 ID token 서명을 보지 않는다. 토큰 엔드포인트에서 직접 받은 응답이라 OIDC Core 3.1.3.7(6)이 허용한다. 문서에 적혀 있다.
|
||||
- 401 뒤 OIDC의 refresh. 세션 복구이지 요청 재전송이 아니다. 두 번째 401은 로그아웃이다(`oidc-pkce-session-owner.ts:623-638`). 함정 6에 걸리지 않는다.
|
||||
- 서버 Envelope `error.message`를 버린다(`backend-envelope.ts:70`). 화면·진단·telemetry 어디에도 실리지 않는다.
|
||||
- path 값 `.`·`..`·`/`·`\`는 인코딩 전에 거절한다. `%`는 `%25`가 되어 dot segment를 만들 수 없다(`http-contract-bridge.ts:194-221`).
|
||||
- 쿠키 recipe의 `credentials: "include"`. 같은 host 조건과 그 이유가 recipe·매뉴얼에 있다(`cookie-session-owner.ts:29-31,54-56`, 매뉴얼 04 4.4).
|
||||
- `scheduler@0.27.0`의 SBOM 분류 차이. `supply-chain.md`에 알려진 차이로 적혀 있다(0929/13-05).
|
||||
@@ -0,0 +1,392 @@
|
||||
# round9 L8 — 가드레일(검사 script)과 문서 정합, 기능 생성 DX
|
||||
|
||||
> round9 리뷰(2026-11-12, 대상 main `5250ff95`)의 영역 기록이다. 서브에이전트가 쓴 원문을 그대로 옮겼다. 바꾼 것은 이 인용 블록과, 작업 폴더 절대 경로를 `(작업 폴더)`로 줄인 것뿐이다. 발견 ID는 이 파일의 이름표(R-01 등)이고, 라운드 ID(`1112/NN-MM`)와의 대응은 [README](2026-11-round9-review.md) 15절이다.
|
||||
|
||||
|
||||
대상: `5250ff95`(트리 `75cc3752`, origin/main). 읽기 전용. repo 파일은 고치지 않았다.
|
||||
|
||||
## 0. 결론
|
||||
|
||||
판정: **고칠 것 있음.** Critical·High 0, Medium 2, Low 17.
|
||||
|
||||
- Medium 둘은 둘 다 "안내대로 하면 틀린 답이 나온다"는 모양이다. ① `scripts/verify.sh parts`가 게이트 명령의 `args`를 버리고 음성 fixture의 진단 문구를 보지 않는다. 그래서 `parts FE-GATE-009`는 merge 게이트가 아니라 release 검토를 돌려 실패하고, `parts FE-GATE-029`는 엉뚱한 이유로 exit 1인 fixture를 통과로 센다(GD-01, w2-fe-2 파일). ② 매뉴얼의 예시 기능 ID `invoice-feature`와 e2e 고정 ID `order-feature`를 템플릿 시험이 사본에서 다시 만든다. 제품이 그 ID(또는 같은 접두어 `invoice`·`order`)로 기능을 만들면 FE-GATE-005·008이 실패하고, `docs/manual/`은 이 사실을 말하지 않고 오히려 그 ID를 1단계 명령 예시로 쓴다(GD-02).
|
||||
- 나머지는 Low다. 사전 점검이 본 단계와 다른 방법으로 확인하는 곳 하나(GD-03), 같은 사실의 손 사본이 이미 갈라진 곳 여럿(문서 검증 안내, 문서 검사 범위, 드릴 복사 목록 위치, 실행 위치 규칙), 훅 N5·N6의 판정과 그 설명의 어긋남, 낡은 문장과 표기다.
|
||||
- 거짓 PASS를 내는 게이트 자체는 찾지 못했다. `check-work-docs.py`(rc=0)와 `scripts/tests`(71건 OK)는 노트북에서 돌려 통과했다.
|
||||
|
||||
## 1. 범위
|
||||
|
||||
- **렌즈(지식 스킬 없음):** `.claude/rules/gates-and-budgets.md`, `.claude/rules/docs.md`, `docs/work/reference/gates.md`, `docs/README.md`, `docs/work/docs-writing.md`. 판정 기준은 `docs/work/reference/review-criteria.md` 2·3·8절, `decisions.md`, `defect-patterns.md`(G5·G7·G9·G11·G12·T7·W1~W3 모양을 대조 기준으로 썼다).
|
||||
- **읽은 코드(전부):** `scripts/lib/docs-system.ts`, `scripts/verify-documentation-readiness.ts`, `scripts/check-work-docs.py`, `scripts/hooks/hooks.py`·`README.md`, `scripts/check-ci-gating.ts`, `scripts/lib/ungated-{scripts,tests}.ts`, `scripts/check-ci-contract.ts`, `scripts/check-type-fixtures.ts`, `scripts/check-typecheck-inputs.ts`, `scripts/check-system-test-prerequisites.ts`, `scripts/check-remediation-ledger.ts`, `scripts/lib/repository-layout.ts`, `scripts/lib/a11y-data-state.ts`, `scripts/lib/removable-template-features.ts`, `scripts/run-ci-gate.ts`(출력 부분), `scripts/verify.sh`(w2-fe-2), `scripts/create-feature.ts` CLI·출력 부분, `scripts/test-feature-scaffold.ts`. **diff만 읽음(bbde570..5250ff95):** `check-adapter-inventory`, `check-architecture`, `check-bundle`, `check-i18n`, `check-test-evidence`, `feature-residue`, `run-isolation`, `vite-build-inputs`, `storybook-static`, `verify-a11y-manual`, `verify-extreme-scale`.
|
||||
- **읽은 문서:** 루트 `README.md`·`AGENTS.md`·`CLAUDE.md`·`PRODUCT.md`, `CHANGELOG.md` 미출시 절(경로 대조), `docs/work/**` 전부, `docs/manual/README.md`·`01`(0~1단계, 9~11단계, merge 절)·`reference/create-feature.md`·`03`(A절, 기능을 지울 때), `docs/operations/ci-quality-gates.md` 앞 1/3과 runner 요구 절, `docs/testing/taxonomy.md`, `.claude/**/*.md`(rules 전부, skills 중 `desktop-gates`·`new-feature`, agents 중 `reviewer`·`verify-app`), `src/*/AGENTS.md` 전부.
|
||||
- **기계 대조(읽기 전용 스크립트, scratchpad `tools/`):** 살아 있는 문서의 `scripts/verify.sh <단계>`·`script <이름>`·`python3 <경로>`·`node <경로>` 인자 대조(틀린 참조 0), 문서에 적힌 `.dependency-cruiser.json` 규칙 이름 대조(0), `CHANGELOG.md` 미출시 절의 백틱 경로 대조(없는 경로는 모두 의도적으로 지운·옮긴 항목), `docs/manual/reference/errors.md` 메시지 표본 대조(코드에서 조립되는 문자열로 확인), 짝 백엔드 pin `45d2a478`의 트리 읽기.
|
||||
- **실행(노트북, pnpm 없이):** `python3 scripts/check-work-docs.py` rc=0. `python3 -m unittest discover -s scripts/tests` 71건 OK. `bash scripts/verify.sh parts FE-GATE-009 --dry-run`, `... parts FE-GATE-029 --dry-run`(python 조회와 printf만 돈다). `scripts/hooks/hooks.py`의 `ran_on_desktop`·`standard_findings`를 python으로 불러 입력별 결과를 봤다.
|
||||
- **게이트 결과(desktop 읽기만):** `/tmp/claude-gates/r9fe-base/summary.txt` — 트리 `75cc3752`, FE-GATE-001~012 rc=0, FE-GATE-013 rc=1(2초), FE-GATE-020 rc=0(991초), 전체 rc=1. `gate-artifacts/FE-GATE-013.txt`: 사전 점검이 `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`로 멈췄다(결정 D8 조건 1의 모양. 조건 2의 `parts FE-GATE-013`은 이 실행에 없다).
|
||||
- **확인 못 한 것:** `parts FE-GATE-013`의 뒤 명령 결과(D8 조건 2). provider·공급망·승격 계열 `scripts/lib/*`(provider-*, supply-chain, ci-artifact-validator, local-release-evidence, promotion-*), `check-architecture.ts`·`check-registries.ts` 내부 판정은 이번에 읽지 않았다(다른 렌즈 몫과 겹치고 diff가 작다). `docs/architecture/**`·`docs/operations/**`의 긴 문서(`scale-architecture.md`, 복구 절차 문서들)는 위 기계 대조와 grep으로만 봤다. 실제 Gitea runner는 꺼져 있어 CI 미검증.
|
||||
|
||||
## 2. 발견
|
||||
|
||||
### GD-01 [w2-fe-2 파일] `scripts/verify.sh parts`가 게이트 명령의 `args`를 버리고 음성 fixture의 진단 문구를 보지 않아, `ci:gate`와 다른 명령을 다른 기준으로 판정한다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 21, 8, 20, 23 |
|
||||
| 심각도·우선순위 | Medium · P2 — merge 게이트 자체는 아니지만, 문서가 판정·검사기 확인에 쓰라고 가리키는 진입점이 틀린 답을 낸다(review-criteria 3절 Medium 예의 "게이트가 틀린 답"과 같은 모양, merge를 직접 막지 않아 P2) |
|
||||
| 통제 | M1 — `gates.md:26`이 parts의 뜻을 적었지만 `args`·`expectedDiagnosticId`를 다루는 시험이 없다(`scripts/tests/test_verify.py:46-58`은 FE-GATE-013 dry-run 하나) |
|
||||
| 증거 | E1 + 노트북 `--dry-run` 출력 |
|
||||
| 근거 | `scripts/verify.sh:58-65` — `gates_json scripts`가 `script`·`expect`·`expectedExitCode`만 찍는다. `scripts/verify.sh:131-145` — `corepack pnpm -s "$script"`만 돌리고, `expect=fail`은 종료 코드만 본다. `config/ci/gates.json:135-140` — FE-GATE-009의 `check-a11y-manual-format`은 `args: ["--", "--format-only"]`. FE-GATE-019·021~025 명령도 `args`가 있다. `scripts/run-ci-gate.ts:129-181` — `ci:gate`는 `args`를 넘기고 `expectedExitCode`와 `expectedDiagnosticId`를 함께 본다. dry-run 출력: `FE-GATE-009 review:a11y-manual: corepack pnpm -s review:a11y-manual`(`--format-only` 없음). `docs/accessibility/route-reviews/*.md` 셋 모두 `Status: pending-manual-review`. 문서가 이 경로를 쓰라고 한다: `docs/work/reference/gates.md:26`, `:66`, `.claude/skills/fe-design-system/SKILL.md:76`("`check:design-system:fixture`가 정해진 오류로 실패해야 통과다") |
|
||||
| 발생 조건 | `scripts/verify.sh parts FE-GATE-009`(또는 019·021~025), 그리고 검사기를 고친 뒤 `parts FE-GATE-029` |
|
||||
| 영향 | FE-GATE-009: `ci:gate`는 통과하는데 parts는 release 단계(FE-GATE-028)의 서명 검토를 돌려 실패한다. FE-GATE-029: 검사기가 깨져 엉뚱한 원인으로 exit 1(예: TypeError)이 나도 parts는 그 음성 fixture를 통과로 센다(G7 거짓 PASS). FE-GATE-013(결정 D8의 조건 2)은 명령에 `args`가 없어 지금은 영향이 없다 |
|
||||
| 최소 개선 방향 | `gates_json scripts`가 `args`(JSON 배열)와 `expectedDiagnosticId`를 함께 내고, `run_parts`가 `args`를 그대로 넘기며 `expect=fail`이면 출력에 진단 문구가 있는지도 본다. 판정 함수를 `run-ci-gate.ts`의 `classifyGateStepResult`와 같은 규칙으로 맞춘다 |
|
||||
| 완료 기준 | `parts FE-GATE-009 --dry-run`이 `... review:a11y-manual -- --format-only`를 보이고, 깨진 음성 fixture에서 `parts FE-GATE-029`가 rc=1 |
|
||||
| RED 시험 | `scripts/tests/test_verify.py`에 (1) `parts FE-GATE-009 --dry-run` 출력에 `--format-only`가 있는지, (2) 가짜 `corepack`(PATH 앞에 둔 셸)이 exit 1과 엉뚱한 문구를 낼 때 `parts FE-GATE-029`가 rc=1인지 보는 시험. 지금 둘 다 실패한다 |
|
||||
|
||||
### GD-02 매뉴얼 예시 ID `invoice-feature`와 e2e 고정 ID `order-feature`로 제품 기능을 만들면 FE-GATE-005·008이 실패하는데, `docs/manual/`은 그 ID를 1단계 예시로 쓰고 경고하지 않는다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 20, 3, 10, 4, 27 |
|
||||
| 심각도·우선순위 | Medium · P2 — "생성 명령으로 기능을 더하면 템플릿 파일을 고치지 않고 merge를 통과한다"(review-criteria 2절)를 깨지만 발생 ID가 좁다. 다운스트림이 그대로 복제하는 기본값(템플릿 시험)이다 |
|
||||
| 통제 | M1 — `docs/work/new-feature.md:59`(AI playbook)에만 "예시 이름이면 묻는다"가 있고, 사람용 `docs/manual/`과 `create:feature`의 거부 조건에는 없다 |
|
||||
| 증거 | E1 |
|
||||
| 근거 | `tests/unit/manual-code-blocks.test.ts:24`, `:98-100` — 저장소 사본(`REMOVAL_FIXTURE_COPY_TARGETS`, `src`·`tests` 포함)에 `create-feature.ts invoice-feature --with-create`를 돌리고 status 0을 기대한다. `scripts/lib/generated-feature.ts:23`, `:54` — FE-GATE-008의 `tests/e2e/generated-feature.spec.ts`·`boot-module-failure.spec.ts`·`old-tab-chunk-recovery.spec.ts`가 사본에 `order-feature`를 만든다. `scripts/create-feature.ts:216`("is already a feature or context"), `:223`(같은 접두어 `base` 거부) — 사본에 같은 ID나 같은 접두어 기능이 있으면 거부한다. 문서: `docs/manual/01-add-a-feature.md:97`(1단계 명령 `create:feature invoice-feature`), `:764`(11단계 `--feature=invoice-feature`), `:790`("매뉴얼 예시 이름으로 만든 기능도 이 단계를 통과한다"), `docs/manual/reference/create-feature.md:167`(`order-feature`를 고정 이름으로만 언급) |
|
||||
| 발생 조건 | 제품이 기능 ID `invoice-feature`·`invoice`·`invoices-feature`처럼 접두어가 `invoice`이거나 `order`인 기능을 만든다(업무 앱에서 흔한 이름) |
|
||||
| 영향 | 사본 생성 단계가 거부해 `test:unit`(FE-GATE-005)과 `test:e2e`(FE-GATE-008)가 기능 코드와 상관없이 실패한다. 매뉴얼을 글자 그대로 따른 사람이 처음 만나는 실패다 |
|
||||
| 최소 개선 방향 | 템플릿 시험이 쓰는 ID를 예약 접두어로 옮긴다(결함 패턴 T7의 `typecheck-probe-*`처럼). 또는 사본에서 같은 ID·접두어 기능을 먼저 지운 뒤 만든다. 그 전까지는 `docs/manual/01` 1단계와 `reference/create-feature.md` 인자 표에 "쓰지 말 ID·접두어"를 적는다 |
|
||||
| 완료 기준 | `invoice-feature`와 `order-feature`를 설치한 사본에서 FE-GATE-005·008이 통과한다 |
|
||||
| RED 시험 | 실험 X-GD02. 시험으로는 `manual-code-blocks.test.ts`·`generated-feature.ts`의 사본 준비 함수에 "이미 같은 ID가 설치된 저장소" 입력을 주는 단위 시험 |
|
||||
|
||||
### GD-03 `test:system` 사전 점검이 provider 본 단계와 다른 방법으로 확인한다 — system bus를 보고 user manager·`systemd-run`·`prlimit`·위임 controller는 보지 않는다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 21, 8, 19, 20 |
|
||||
| 심각도·우선순위 | Low · P2 — 결함 패턴 G5의 반복이다(같은 파일, 1105/12-01은 namespace만 고쳤다). PASS 뒤 provider 테스트가 이름 붙은 오류로 떨어지므로 1105/12-01(원문 오류)보다 좁다 |
|
||||
| 통제 | M2 — 점검이 실행 파일 셋, cgroup 루트, system bus, bwrap namespace만 실제로 해 본다 |
|
||||
| 증거 | E1 |
|
||||
| 근거 | `scripts/check-system-test-prerequisites.ts:59-72`(bwrap·systemctl·tar만), `:74-81`(`/sys/fs/cgroup/cgroup.controllers`가 비지 않았는지만), `:83-88`(`systemctl show-environment` — system manager), `:153`(`System test prerequisites: PASS`). 본 단계: `scripts/run-and-validate-provider.ts:116-127`(`/usr/bin/prlimit`, `/usr/bin/systemd-run` 필요), `:494-503`(`systemctl --user show --property=Version`, 254 이상), `scripts/lib/provider-cgroup.ts:82-84`(`systemd-run --user --scope`). 요구 목록은 이미 적혀 있다: `docs/operations/ci-quality-gates.md:177-182`, `.gitea/workflows/quality-gates.yml:80`. `tests/unit/system-test-prerequisites.test.ts`에 user manager·`systemd-run`·`prlimit` 사례가 없다. `gates.md:92`("본 단계가 쓰는 것과 같은 방법으로 한 번 실행해 본다. 존재 여부만 보는 점검은 UNVERIFIED") |
|
||||
| 발생 조건 | user namespace는 되지만 사용자 systemd manager가 없거나(컨테이너 runner, lingering 없는 ssh) 254 미만, 또는 `prlimit`·`systemd-run`이 없는 호스트 |
|
||||
| 영향 | 점검이 PASS를 찍은 뒤 provider 테스트가 하나씩 `provider cgroup unavailable: ...`로 실패한다. 결정 D8의 조건 1("실패가 사전 점검의 user namespace 제한 하나뿐")을 판정할 때 점검이 다른 호스트 원인을 놓친다 |
|
||||
| 최소 개선 방향 | 점검이 본 단계와 같은 호출을 한다: `systemctl --user show --property=Version --value`(254 이상), `/usr/bin/prlimit`·`/usr/bin/systemd-run` 실행 가능, 가능하면 `systemd-run --user --scope --collect -- /bin/true` 한 번. 한 번 해 보지 못하는 조건(위임 controller 값)은 `UNVERIFIED`로 적는다 |
|
||||
| 완료 기준 | user bus가 없는 환경에서 점검이 그 원인을 이름으로 대며 exit 1 |
|
||||
| RED 시험 | `tests/unit/system-test-prerequisites.test.ts`에 가짜 host: `systemctl show-environment`는 0, `systemctl --user show`는 실패 → 지금은 `[]`(PASS)라 실패하는 시험 |
|
||||
|
||||
### GD-04 지침·작업 매뉴얼 문서의 검증 안내가 갈라졌고, 편집 훅 N5도 그 문서들을 노트북에서 끝나는 파일로 센다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(손 사본이 이미 다르다) |
|
||||
| 관련 관점 | 21, 9, 23, 20 |
|
||||
| 심각도·우선순위 | Low · P2 — 따르면 merge 게이트(FE-GATE-005 안의 `documentation-readiness.test.ts`)에서야 실패를 안다. 게이트는 잡는다 |
|
||||
| 통제 | 안내 M1, 결함 자체는 M3(FE-GATE-005가 잡는다) |
|
||||
| 증거 | E1 |
|
||||
| 근거 | 노트북 검사로 끝난다고 쓴 곳: `AGENTS.md:29`("문서·지침을 고쳤으면 `scripts/verify.sh docs`(노트북)"), `docs/work/reference/gates.md:54`(작업 매뉴얼·훅 → 노트북 둘만), `docs/work/experts.md:70`, `scripts/hooks/README.md:29`("`.claude/`, `CLAUDE.md`, `src/**/AGENTS.md` ... `scripts/verify.sh docs`·`hooks`가 노트북에서 본다"), `scripts/hooks/hooks.py:75-83`(`LAPTOP_ONLY`), 그것을 굳힌 시험 `scripts/tests/test_hooks.py:246`. 반대로 desktop `verify:documentation`도 필요하다고 쓴 곳: `docs/work/README.md:75`, `.claude/rules/docs.md:11`·`:15`, `docs/work/docs-writing.md:41-42`·`:52`. 코드: `scripts/lib/docs-system.ts:728-731`(`livingDocuments`), `scripts/verify-documentation-readiness.ts:343-346` — `.claude/**/*.md`, 루트 `CLAUDE.md`·`AGENTS.md`, `src/**/AGENTS.md`의 경로·script·게이트 ID와 언어·문체를 본다. `check-work-docs.py`는 분량·이력 ID·뼈대·상대 링크만 본다 |
|
||||
| 발생 조건 | `.claude/skills/*.md`나 `AGENTS.md`에 없는 경로·script를 백틱으로 쓰거나 영어 문단·높임말을 넣는다 |
|
||||
| 영향 | 노트북 검사·훅이 모두 조용하고, PR의 FE-GATE-005에서 실패한다. N5는 턴 끝 알림도 하지 않는다 |
|
||||
| 최소 개선 방향 | `AGENTS.md:29`·`gates.md:54`·`experts.md:70`에 "살아 있는 문서면 desktop `scripts/verify.sh script verify:documentation`"을 더한다. `hooks.py` `LAPTOP_ONLY`에서 `.md` 문서(`.claude/**/*.md`, `CLAUDE.md`, `src/**/AGENTS.md`)를 빼고, README 29줄과 시험을 같이 고친다 |
|
||||
| 완료 기준 | 안내 문장들이 한 규칙을 말하고, `.claude/rules/x.md`만 고친 세션에서 N5가 한 번 알린다 |
|
||||
| RED 시험 | `test_hooks.py`: `.claude/rules/x.md`를 고친 뒤 stop이 알림을 낸다(지금은 `None`) |
|
||||
|
||||
### GD-05 검사 script를 고칠 때의 규칙이 `merge`만 돌리라고 해서, main 단계로 옮긴 검사기 자기 시험(FE-GATE-029)이 PR 전에 돌지 않는다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 21, 10, 9 |
|
||||
| 심각도·우선순위 | Low · P2 — main 단계로 옮긴 것은 소유자 결정(2026-11-07, 커밋 `f6b2b96c` 본문의 "위험: 검사기를 망가뜨린 PR은 merge를 통과하고 main에서 빨개진다")이다. 결함은 그 위험을 줄일 안내가 경로별 규칙과 게이트 표에 없다는 것이다 |
|
||||
| 통제 | M1 — 일부 스킬에만 있다(`.claude/skills/fe-security/SKILL.md:71`, `fe-design-system/SKILL.md:76`, `fe-testing/SKILL.md:61`) |
|
||||
| 증거 | E1 |
|
||||
| 근거 | `.claude/rules/gates-and-budgets.md:21-22`(paths에 `scripts/check-*.ts` 포함, "새 검사에는 통과 fixture와 거절 fixture를 함께 둔다 … 바꾼 뒤 desktop에서 `scripts/verify.sh merge`"). `docs/work/reference/gates.md:44-54` 표에 검사기를 바꿀 때의 행이 없다. `config/ci/gates.json` stages: FE-GATE-029는 `main`, 음성 fixture `*:fixture` 15개와 `check:ci:gating`이 거기 있다 |
|
||||
| 발생 조건 | `scripts/check-design-system.ts` 같은 검사기를 고치고 규칙대로 `merge`만 돌린다 |
|
||||
| 영향 | 검사기의 음성 fixture가 PR에서 돌지 않아, 검사기를 망가뜨린 변경이 main에 들어간 뒤 FE-GATE-029가 빨개진다 |
|
||||
| 최소 개선 방향 | 규칙 21~22줄과 `gates.md` 2절 표에 "검사 script·fixture를 바꿀 때: merge에 더해 `scripts/verify.sh gate FE-GATE-029`"를 한 줄 더한다(GD-01을 고치기 전에는 `parts`가 아니라 `gate`) |
|
||||
| 완료 기준 | 경로 규칙과 게이트 표가 FE-GATE-029를 말한다 |
|
||||
| RED 시험 | 문서 시험이 없다. `tests/unit/`에 "`.claude/rules/gates-and-budgets.md`가 main 단계 게이트 ID를 모두 언급한다" 같은 대조를 둘 수 있다 |
|
||||
|
||||
### GD-06 `verify:documentation`의 명령 경로·script 검사가 이 repo의 주 진입점 `scripts/verify.sh …`와 `python3 …` 명령을 보지 않는다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험(지금 틀린 참조는 0) |
|
||||
| 관련 관점 | 21, 9, 10 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제 | M2 — 검사는 있지만 범위가 문서가 말하는 것보다 좁다 |
|
||||
| 증거 | E1 + 노트북 대조 스크립트(살아 있는 문서의 `scripts/verify.sh` 인자·`python3`·`node` 경로, 틀린 것 0) |
|
||||
| 근거 | `scripts/verify-documentation-readiness.ts:307-316` — 명령 머리가 `corepack, pnpm, npx, node, vitest, playwright, tsc, eslint, bash, sh`일 때만 인자 경로를 본다. 그래서 `` `scripts/verify.sh exec -- node scripts/run-vitest.ts run <파일>` `` 안의 `scripts/run-vitest.ts`, `` `python3 scripts/check-work-docs.py --history <경로>` `` 안의 경로는 보지 않는다(공백이 든 토큰이라 `namedPath`도 건너뛴다, `:285`). `:395-400` — script 이름은 `corepack pnpm <이름>`이나 백틱 바로 뒤의 `<prefix>:<name>`만 보므로 `` `scripts/verify.sh script verify:documentaton` `` 같은 오타를 놓친다. 문서는 일반적으로 본다고 쓴다: `docs/work/reference/gates.md:107`, `docs/README.md:174`, `.claude/rules/docs.md:11`. 시험 `tests/unit/documentation-readiness.test.ts:234-254`에 이 모양이 없다 |
|
||||
| 발생 조건 | 작업 매뉴얼·스킬에 `scripts/verify.sh` 명령으로 없는 파일·script를 적는다(이 repo 문서의 명령 대부분이 이 꼴이다) |
|
||||
| 영향 | 낡은 명령이 게이트를 통과해 남는다(결함 패턴 W1) |
|
||||
| 최소 개선 방향 | `COMMAND_HEADS`에 `python3`를 더하고, `scripts/verify.sh`는 `exec --` 뒤를 다시 명령으로 읽고 `script` 뒤 낱말을 package script로 대조한다 |
|
||||
| 완료 기준 | 아래 RED 시험 통과 |
|
||||
| RED 시험 | `documentation-readiness.test.ts`의 `it.each`에 `` `scripts/verify.sh exec -- node scripts/no-such.ts` ``, `` `python3 scripts/no-such.py` ``, `` `scripts/verify.sh script no:such-script` ``를 더해 실패를 기대한다(지금 status 0). 실험 X-GD06 |
|
||||
|
||||
### GD-07 문서 검사 범위를 적은 손 사본 셋이 서로 다르다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(손 사본이 이미 다르다) |
|
||||
| 관련 관점 | 23, 9, 21 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제 | M1 |
|
||||
| 증거 | E1 |
|
||||
| 근거 | `docs/operations/ci-quality-gates.md:111-127` — 범위를 "`docs/README.md` 1절의 현재 계약 문서"로 적고, 문서 체계 검사 여섯(language·head·number·map·readme·style)과 R6·R7을 빠뜨리며, "수치 … 맞는지는 검사하지 않는다"고 쓴다. 코드는 살아 있는 문서 전부(`verify-documentation-readiness.ts:343-346`)와 문서 체계 검사(`:457`)와 복사한 숫자 검사(`docs-system.ts` `checkNumber`)를 돈다. `docs/work/reference/gates.md:106` — "기록(`docs/design/`, `docs/history/`, `docs/adr/`)은 머리 블록만 본다". 코드는 결정 기록(`docs/adr/`) 본문의 언어·문체를 본다(`docs-system.ts:283`, `:527`). `docs/README.md:172`·`:178`이 맞다 |
|
||||
| 발생 조건 | 운영 문서나 게이트 기준을 보고 문서를 고친다 |
|
||||
| 영향 | 검사 범위를 좁게 알고 `.claude/`·`docs/work/` 문서나 VD 본문을 검사 밖이라 여긴다 |
|
||||
| 최소 개선 방향 | `ci-quality-gates.md` 해당 목록을 `docs/README.md` 5절을 가리키는 한 줄로 바꾸고, `gates.md:106`에 "결정 기록은 본문의 언어·문체도 본다"를 더한다 |
|
||||
| 완료 기준 | 세 문서가 같은 범위를 말한다(또는 둘이 `docs/README.md` 5절을 가리킨다) |
|
||||
| RED 시험 | 없음(문장 대조). 리뷰 표본 대조로 확인 |
|
||||
|
||||
### GD-08 `create:feature` 참조 문서가 초기 JS 기록 다시 쓰기를 빠뜨린다 — 머리 문장, 출력 예시, 되돌리기가 모두
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 20, 9, 27, 3 |
|
||||
| 심각도·우선순위 | Low · P3 — 실패 메시지가 다시 쓰는 명령을 말한다 |
|
||||
| 통제 | M3 — `test:unit`이 기록과 빌드를 대조한다 |
|
||||
| 증거 | E1 |
|
||||
| 근거 | `docs/manual/reference/create-feature.md:3`("모든 merge 게이트를 통과하는 가장 작은 기능을 만드는 명령이다"), `docs/manual/README.md:6`(같은 주장). `create-feature.md:117-126` 출력 예시는 `Next:` 1·2만 보이고 3(초기 JS 기록)을 `...`로 지운다. `create-feature.md:136-145` 되돌리기는 `rm`·`generate:feature-index`·`write-dev-release-manifest.ts`만 적는다. 반면 `docs/manual/03-outside-feature-folder.md:262`는 지울 때 `measure-feature-shape-growth.ts --initial-baseline --write`도 돌린다고 쓴다. 코드: `scripts/create-feature.ts:1768-1779`(`Next:` 3), `scripts/test-feature-scaffold.ts:72-94`(드릴도 생성 뒤 기록을 다시 쓰고서야 게이트를 돈다), 허용 오차 `scripts/scale/measure-feature-shape-growth.ts:250`(256 B) 대 첫 기능 비용 `config/scale/feature-shape-ceilings.json` `firstFeatureGzipBytes` 6,327 |
|
||||
| 발생 조건 | 참조 문서만 보고 생성 뒤 바로 merge를 돌리거나, `Next:` 3을 한 뒤 참조 문서의 되돌리기로 기능을 지운다 |
|
||||
| 영향 | FE-GATE-005의 `tests/unit/feature-shape-growth.test.ts`가 기록 drift로 실패한다 |
|
||||
| 최소 개선 방향 | 머리 문장에 "생성 뒤 `Next:` 3의 기록 다시 쓰기까지"를 붙이고, 출력 예시에 3을 보이고, 되돌리기에 같은 명령을 더하거나 03 「기능을 지울 때」를 가리킨다 |
|
||||
| 완료 기준 | 참조 문서와 03이 같은 절차를 말한다 |
|
||||
| RED 시험 | 실험 X-GD08 |
|
||||
|
||||
### GD-09 편집 훅 N5가 `verify.sh`를 읽거나 `--dry-run`만 해도 "desktop 실행"으로 세어 알림을 지운다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 21, 20 |
|
||||
| 심각도·우선순위 | Low · P3 — 알림(넛지)이고 게이트가 아니다 |
|
||||
| 통제 | M2 |
|
||||
| 증거 | E1 + 노트북에서 함수 실행(`hooks.ran_on_desktop`) |
|
||||
| 근거 | `scripts/hooks/hooks.py:86`(`VERIFY` — `scripts/verify.sh` 뒤 첫 낱말을 단계로 본다), `:280-295`. 실행 결과: `scripts/verify.sh merge --dry-run` → True, `sed -n 1,80p scripts/verify.sh && ls` → True(단계 `&&`), `grep -n foo scripts/verify.sh config/ci/gates.json` → True, `git log -- scripts/verify.sh docs/work` → True, `ssh desktop 'cat …/FE-GATE-005.log \| grep vitest'` → True. README는 "돌린 명령"만 센다고 쓴다(`scripts/hooks/README.md:28`) |
|
||||
| 발생 조건 | 파일을 고친 세션이 `verify.sh`를 읽거나 dry-run하거나 desktop 로그를 grep한다 |
|
||||
| 영향 | 턴 끝 알림(꼭 지킬 것 5 상기)이 나오지 않는다 |
|
||||
| 최소 개선 방향 | 단계 낱말이 `config/ci/gates.json`의 stage id나 `gate·parts·script·exec`일 때만 세고, `--dry-run`이 있으면 세지 않는다. ssh 쪽은 `cat`·`grep`·`tail`만인 명령을 뺀다 |
|
||||
| 완료 기준 | 위 다섯 입력이 False |
|
||||
| RED 시험 | `test_hooks.py` `test_laptop_commands_and_other_hosts_do_not_count`에 위 입력을 더한다(지금 실패) |
|
||||
|
||||
### GD-10 경로별 규칙이 "편집 훅(N6)이 이 파일들의 편집을 알린다"고 하지만 N6은 그중 일부만 본다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 21, 9, 23 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제 | M1 |
|
||||
| 증거 | E1 + 노트북에서 `hooks.standard_findings` 실행 |
|
||||
| 근거 | `.claude/rules/gates-and-budgets.md:2-10`(paths: `config/ci/**`, `config/performance/**`, `config/scale/**`, `config/testing/**`, `.gitea/**`, `scripts/run-ci-gate.ts`, `scripts/contracts/**`, `scripts/check-*.ts`), `:23`. `scripts/hooks/hooks.py:57-66`(`GATE_STANDARDS`: budgets·scale·testing·ungated·baseline·vitest.config·snapshot). 실행: `config/ci/gates.json`, `.gitea/workflows/quality-gates.yml`, `scripts/run-ci-gate.ts`, `scripts/contracts/ci-gates.ts`, `scripts/check-bundle.ts` → 알림 없음 |
|
||||
| 발생 조건 | `config/ci/gates.json`에서 명령을 빼거나 `expect`를 바꾸는 등 게이트를 낮추는 편집 |
|
||||
| 영향 | 규칙을 믿은 사람은 알림이 없으니 기준 파일이 아니라고 여긴다 |
|
||||
| 최소 개선 방향 | 규칙 문장을 "N6은 예산·기준선·ungated 목록·스냅숏 편집을 알린다(`scripts/hooks/README.md` 2절)"로 좁히거나, `GATE_STANDARDS`에 `config/ci/gates.json`을 더한다 |
|
||||
| 완료 기준 | 규칙 문장과 `GATE_STANDARDS`가 같은 파일 집합을 말한다 |
|
||||
| RED 시험 | `test_hooks.py`에 `config/ci/gates.json` 편집이 N6 알림을 내는지(코드를 넓히는 쪽을 고르면) |
|
||||
|
||||
### GD-11 `.claude/rules/tests.md`의 「돌리는 법」이 실행 위치의 정본(`operate.md` 4.1절)과 다르고, 적힌 그대로는 한 파일을 돌리지 못한다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(손 사본이 이미 다르다) |
|
||||
| 관련 관점 | 20, 23, 9 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제 | M1 — `docs-writing.md:59`("소유자 환경 규칙은 `operate.md` 4.1절과 `delegate.md` 4.3절에만") |
|
||||
| 증거 | E1 |
|
||||
| 근거 | `.claude/rules/tests.md:25`("한 파일도 desktop에서: `scripts/verify.sh script test:unit`, 또는 `ssh desktop`으로 `node scripts/run-vitest.ts run <file>`"). `test:unit`은 `tests/unit` 전체를 돈다(`package.json`). 맨 `ssh desktop`은 desktop 공유 checkout(다른 트리·브랜치)에서 돌고, 비대화형 ssh에는 node가 PATH에 없다(`docs/work/operate.md:42`). 정본: `docs/work/operate.md:41`(`scripts/verify.sh exec -- node scripts/run-vitest.ts run <파일>`), `:35`(공유 checkout을 건드리지 않는다). `operate.md:97`도 "`ssh desktop`으로 돌린다"고 적어 같은 문서 안에서 어긋난다 |
|
||||
| 발생 조건 | 시험 파일을 고친 세션이 경로 규칙대로 한 파일을 돌린다 |
|
||||
| 영향 | 전체 suite를 돌리거나, 노트북 트리가 아닌 공유 checkout을 시험하거나, node가 없어 실패한다 |
|
||||
| 최소 개선 방향 | 규칙 25줄을 `operate.md` 4.1절을 가리키는 한 줄과 `scripts/verify.sh exec -- node scripts/run-vitest.ts run <파일>`로 바꾸고, `operate.md:97`도 맞춘다 |
|
||||
| 완료 기준 | 한 파일 실행 방법이 한 곳에서 한 가지다 |
|
||||
| RED 시험 | 없음(문장) |
|
||||
|
||||
### GD-12 드릴 복사 목록의 위치를 `scripts/lib/removal-fixture.ts`로 적은 문서 여섯이 낡았다 — 목록은 `config/repository-layout.json`의 집합이다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 9, 27, 23 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제 | M1 |
|
||||
| 증거 | E1 |
|
||||
| 근거 | 목록 정의: `config/repository-layout.json`(집합 `fixture-copy`·`fixture-documents`), `scripts/lib/removal-fixture.ts:35`, `:52`(`selectRepositoryPaths(...)` 호출만 남음). 낡은 문장: `.claude/rules/docs.md:11`, `docs/work/docs-writing.md:37`, `docs/work/reference/gates.md:110`, `docs/work/reference/structure.md:119`("이 목록 하나만 쓴다"), `.claude/skills/fe-structure/SKILL.md:65`, `docs/work/reference/defect-patterns.md:25`(G11 막는 기준). `docs/manual/03-outside-feature-folder.md:230`(R1·R2)과 `CHANGELOG.md:70`은 등록부를 맞게 가리킨다 |
|
||||
| 발생 조건 | 문서에서 마크다운 링크를 걸 수 있는 루트 파일을 확인하거나, 드릴 복사 대상을 고친다 |
|
||||
| 영향 | `removal-fixture.ts`에서 목록을 찾지 못하거나 거기서 목록을 고치려 한다 |
|
||||
| 최소 개선 방향 | 여섯 곳을 "`config/repository-layout.json`의 `fixture-copy`·`fixture-documents` 집합(`scripts/lib/removal-fixture.ts`가 고른다)"으로 바꾼다 |
|
||||
| 완료 기준 | `git grep -n "removal-fixture.ts" -- '*.md'`의 살아 있는 문서 줄이 등록부를 함께 가리킨다 |
|
||||
| RED 시험 | 없음(문장) |
|
||||
|
||||
### GD-13 `ci:gate`의 실패 출력이 실패한 명령도, 원인이 남은 로그 경로도 말하지 않는다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 8, 20, 21 |
|
||||
| 심각도·우선순위 | Low · P3 — 원인은 `artifacts/quality/gates/FE-GATE-0NN.txt`에 있고 workflow가 `if: always()`로 올린다 |
|
||||
| 통제 | M2 |
|
||||
| 증거 | E1 + desktop 로그 읽기 |
|
||||
| 근거 | `scripts/run-ci-gate.ts:58-66`(`appendOutput`은 버퍼에만 쌓는다), `:243-246`(콘솔에는 `${gateId} ${gate.name}: FAIL`만). desktop `/tmp/claude-gates/r9fe-base/FE-GATE-013.log`(이번 실행) 전체가 세 줄: `$ node … run-ci-gate.ts FE-GATE-013`, `FE-GATE-013 security: FAIL`, `[ELIFECYCLE] …`. 규칙 `.claude/rules/gates-and-budgets.md:21`("실패 메시지는 넘은 항목·잰 값·고칠 파일을 말한다"), 결함 패턴 G12 |
|
||||
| 발생 조건 | 어느 게이트든 실패 |
|
||||
| 영향 | CI step 로그·`verify.sh` 단계 로그만 보는 사람은 원인과 다음 파일을 모른다(이번 리뷰도 실행이 끝나 `gate-artifacts/`가 복사되기 전에는 FE-GATE-013 원인을 볼 수 없었다) |
|
||||
| 최소 개선 방향 | FAIL 줄에 실패한 명령 id와 로그 경로를 붙이고, 그 명령 출력의 마지막 몇 줄을 stderr로 낸다 |
|
||||
| 완료 기준 | 실패한 `ci:gate`의 stderr가 명령 id·로그 경로·원인 줄을 담는다 |
|
||||
| RED 시험 | `run-ci-gate` 시험(가짜 명령이 exit 1)에서 stderr에 로그 경로가 있는지 본다(지금 실패) |
|
||||
|
||||
### GD-14 2026-11-07 소유자가 승인한 "검사기 자기 시험·gating 검사를 main 단계로, CI 계약 기준선 삭제" 결정이 결정 색인에 없다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 26, 9, 23 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제 | M1 — `decisions.md` 1절 "결정은 한 곳에 적고 다시 묻지 않는다" |
|
||||
| 증거 | E1 |
|
||||
| 근거 | 결정의 출처는 커밋 `f6b2b96c` 본문("소유자 승인 2026-11-07", design-docs `repo-structure/03-ci.md` 7.3절 F2)뿐이다. `docs/work/reference/decisions.md` 2.1·2.2절, `docs/work/evidence.md`, `docs/adr/`에 FE-GATE-029·main 단계·기준선 삭제 행이 없다(`grep` 0건). 게이트 기준을 바꾸는 결정은 색인에 적는다(`.claude/rules/gates-and-budgets.md:17`) |
|
||||
| 발생 조건 | 다음 리뷰가 "음성 fixture가 PR에서 돌지 않는다"를 본다 |
|
||||
| 영향 | 정한 결정을 결함으로 다시 올리게 된다(이번 리뷰도 커밋 본문까지 가서야 결정임을 확인했다) |
|
||||
| 최소 개선 방향 | `decisions.md` 2.2절에 한 행: 날짜, 무엇을(FE-GATE-029 `main` 단계, `*:fixture` 15개·`check:ci:gating` 이동, 기준선 파일 삭제), 버린 안, 위험(main에서 빨개짐), 출처 |
|
||||
| 완료 기준 | 색인에 행이 있다 |
|
||||
| RED 시험 | 없음 |
|
||||
|
||||
### GD-15 살아 있는 문서 아홉이 라운드 없는 리뷰 ID(`리뷰 12-05`)를 출처로 쓴다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 9, 24, 26 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제 | M1 — `docs/work/docs-writing.md:31`("다른 문서는 리뷰 ID를 출처로 둘 수 있다(꼴은 `MMDD/NN-MM`)"). 기계 검사는 `CHANGELOG.md`에만 있다 |
|
||||
| 증거 | E1 |
|
||||
| 근거 | `docs/operations/ci-quality-gates.md:39`, `:58`, `:90`, `:127`, `:133`, `docs/architecture/layers.md:106`, `:147`, `:168`, `:189`, `docs/architecture/capability-consumer-experience.md:23`, `docs/architecture/optional-adapter-recipes.md:204`, `docs/architecture/static-delivery.md:37`, `docs/operations/performance-evidence.md:104`, `docs/operations/release-cache-rollback.md:15`, `:59`, `docs/security/browser-boundary.md:12`, `docs/security/supply-chain.md:44`, `:67`. 라운드마다 `NN-MM`을 새로 매기므로(`CHANGELOG.md:11`) 어느 리뷰인지 정해지지 않는다. 대부분 2026-09-25 라운드에서 들어왔다(예: `39b9fbff`) |
|
||||
| 발생 조건 | 근거를 따라 리뷰 문서를 찾는다 |
|
||||
| 영향 | 다른 라운드의 같은 번호 발견으로 잘못 간다 |
|
||||
| 최소 개선 방향 | `0925/12-05`처럼 라운드를 붙인다. 필요하면 `tests/unit/changelog-review-ids.test.ts`의 판정을 살아 있는 문서에도 건다 |
|
||||
| 완료 기준 | `git grep -nE "(리뷰\|review) [0-9]{2}-[0-9]{2}" -- '*.md'`가 기록·`evidence.md` 밖에서 0줄 |
|
||||
| RED 시험 | 위 판정을 살아 있는 문서에 거는 단위 시험 |
|
||||
|
||||
### GD-16 `gates.md` 2절이 FE-GATE-012를 "merge에 더해" 돌리라고 쓴다 — FE-GATE-012는 merge 단계에 있다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함(낡은 문장) |
|
||||
| 관련 관점 | 9, 23 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제 | M1 |
|
||||
| 증거 | E1 |
|
||||
| 근거 | `docs/work/reference/gates.md:52`("merge에 더해 `check:bundle`(FE-GATE-012)과 lab 게이트 `test:performance`(FE-GATE-026)"). `config/ci/gates.json` merge `gateIds`에 FE-GATE-012가 있다. `docs/work/reference/performance.md:6`은 "merge 단계"로 맞게 쓴다 |
|
||||
| 발생 조건 | 화면·청크를 바꾼 작업이 돌릴 게이트를 고른다 |
|
||||
| 영향 | 같은 게이트를 두 번 돌리거나 FE-GATE-012가 merge 밖이라 여긴다 |
|
||||
| 최소 개선 방향 | "merge 단계(FE-GATE-012 포함)에 더해 lab 게이트 FE-GATE-026" |
|
||||
| 완료 기준 | 문장 수정 |
|
||||
| RED 시험 | 없음 |
|
||||
|
||||
### GD-17 지금 동작(실행 격리 변수 표)을 설계 기록에서만 찾게 한다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 확인된 결함 |
|
||||
| 관련 관점 | 9, 4, 26 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제 | M1 — `docs/README.md:70`("설계서와 기록은 … 지금 동작을 설명하지 않는다"), `docs/manual/README.md:70`("지금 구조가 아닌 설명은 링크하지 않는다") |
|
||||
| 증거 | E1 |
|
||||
| 근거 | `README.md:221`, `docs/manual/01-add-a-feature.md:817`이 `TEST_RUN_ID`·포트 변수 표를 `docs/design/2026-07-26-frontend-platform-testing-strategy-design.md` 13.6절로 가리킨다. 그 설계서 머리 블록은 상태 「확인 안 함」, 현재 정본 `docs/testing/taxonomy.md`인데 taxonomy에는 그 표가 없다. 표의 코드 정본은 `scripts/lib/run-isolation.ts`(`TEST_PORT_VARIABLES`) |
|
||||
| 발생 조건 | 한 checkout에서 두 실행을 나누려는 사람 |
|
||||
| 영향 | 기록은 머리 블록만 고치는 문서라(`.claude/rules/docs.md:9`) 다음 변수 변경을 따라갈 곳이 없다. 지금은 표가 코드와 같다(`TEST_VISUAL_WORKSHOP_PORT`까지 있다) |
|
||||
| 최소 개선 방향 | 표를 `docs/testing/taxonomy.md`로 옮기거나 `scripts/lib/run-isolation.ts`를 정본으로 가리킨다 |
|
||||
| 완료 기준 | 살아 있는 문서가 기록 문서를 지금 동작의 출처로 가리키지 않는다 |
|
||||
| RED 시험 | 없음 |
|
||||
|
||||
### GD-18 문서가 적은 짝 백엔드 기준이 pin과 다르다
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 미검증(표기는 확인된 어긋남, 내용 영향은 미확인) |
|
||||
| 관련 관점 | 17, 9, 26 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제 | M1 — 짝 기준 커밋은 `config/contracts/backend-contract-pin.json`(`docs/README.md:48`) |
|
||||
| 증거 | E1(짝 repo 읽기) |
|
||||
| 근거 | `docs/manual/04-paired-backend-session.md:10`("이 문서의 백엔드 사실은 백엔드 `bbe944bd` 기준이다"). pin은 `45d2a478`이다. 두 커밋 사이(10커밋) 백엔드의 `docs/manual/07-authorization.md`, `SampleDemoAccountsProductionGuard.java`, `SampleDemoSecurityConfigTest.java` 등 인증 관련 8파일이 바뀌었다. `AGENTS.md:3`("개발 compose는 짝 백엔드의 `compose.yaml`을 쓴다") — pin 트리의 루트에는 `docker-compose*.yml`만 있고 `compose.yaml`은 백엔드 HEAD(`a7e38c10`, pin보다 238커밋 뒤)에만 있다. 백틱 안 낱말에 `/`가 없어 문서 검사가 보지 않는다 |
|
||||
| 발생 조건 | pin 기준으로 짝 백엔드를 받은 제품 |
|
||||
| 영향 | 04의 인증 설정 사실이 pin과 다를 수 있다(미확인). `compose.yaml`은 pin에 없다 |
|
||||
| 최소 개선 방향 | 04를 pin `45d2a478`에서 다시 대조해 기준 표기를 pin으로 바꾸고, `AGENTS.md`는 pin에 있는 파일을 가리키거나 pin을 올린다(pin 갱신은 짝 계약 결정) |
|
||||
| 완료 기준 | 문서의 백엔드 기준 표기가 pin과 같다 |
|
||||
| RED 시험 | 실험 X-GD18(drift 검사) |
|
||||
|
||||
### GD-19 손으로 옮긴 숫자 두 곳(아직 같다)
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 성격 | 구조적 위험 |
|
||||
| 관련 관점 | 9, 23 |
|
||||
| 심각도·우선순위 | Low · P3 |
|
||||
| 통제 | M1 — `docs/work/docs-writing.md:33`("숫자를 복제하지 않는다") |
|
||||
| 증거 | E1 |
|
||||
| 근거 | `docs/work/README.md:73`(분량 상한 40·15·200·80·150·350)은 `scripts/check-work-docs.py:70-77`의 상수 사본이다. `CLAUDE.md:10`("`fe-*` 스킬 9개")은 `.claude/skills/fe-*` 개수 사본이다. 둘 다 지금은 같다. 문서 검사의 `number`는 프레임워크 버전과 게이트·recipe·adapter 개수만 본다 |
|
||||
| 발생 조건 | 상한이나 스킬 수를 바꾼다 |
|
||||
| 영향 | 다음 변경에서 낡는다(결함 패턴 W1) |
|
||||
| 최소 개선 방향 | README 8절은 "상한은 `scripts/check-work-docs.py`가 출력한다"로, CLAUDE.md는 개수를 빼고 명단(`docs/work/experts.md`)을 가리킨다 |
|
||||
| 완료 기준 | 숫자 사본 0 |
|
||||
| RED 시험 | 없음 |
|
||||
|
||||
## 3. 넘길 것
|
||||
|
||||
- → 짝 계약(fe-react 또는 백엔드 repo 세션): 짝 백엔드 HEAD가 pin `45d2a478`보다 238커밋 앞서 있고, 그 사이 `scripts/new-feature.sh`(10줄)와 `docs/web/http-contract.md`(4줄)가 바뀌었다. `create:feature`가 옮긴 사실과 6.1절 답 표가 아직 맞는지는 `check:backend-contract-drift`(게이트 밖)로만 안다. 실험 X-GD18.
|
||||
- → fe-performance: `checkoutBuildReadFailure`(1106/12-02 수정)는 `check-bundle.ts`·`generate-supply-chain.ts`만 쓴다. 같은 FE-GATE-012의 `check:app-build-input:bundle`, `check:optional-recipes --require-dist`도 `dist/`를 읽는다. `RUN_OUTPUT_ROOT`는 Playwright 설정만 넘기므로 지금 경로에서는 닿지 않는다고 봤다(확인은 그 렌즈 몫).
|
||||
- → 총괄: GD-01은 w2-fe-2가 바꾸는 `scripts/verify.sh`다. D8 판정(`parts FE-GATE-013`)은 그 게이트 명령에 `args`가 없어 지금 영향이 없다.
|
||||
|
||||
## 4. 실험 요청
|
||||
|
||||
| ID | 명령 | env | 상한 | 기대 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| X-GD01a | `scripts/verify.sh parts FE-GATE-009 --log r9-gd01-parts009` | 기본(CI env는 스크립트가 준다) | 10분 | parts의 `review:a11y-manual` rc≠0(서명 없는 기록 셋), 같은 트리의 `gate FE-GATE-009`는 rc=0(r9fe-base) |
|
||||
| X-GD01b | 아래 패치를 얹고 `scripts/verify.sh parts FE-GATE-029 --log r9-gd01-parts029`와 `scripts/verify.sh gate FE-GATE-029 --log r9-gd01-gate029` | 기본 | 15분 | parts는 `check:design-system:fixture`를 통과로 세고, gate는 `expected negative fixture identity`로 실패 |
|
||||
| X-GD02 | `scripts/verify.sh exec -- bash -c 'corepack pnpm -s create:feature invoice-feature && node scripts/run-vitest.ts run tests/unit/manual-code-blocks.test.ts'` | 기본 | 10분 | rc≠0, 출력에 `feature id invoice-feature is already a feature or context` |
|
||||
| X-GD02b | `scripts/verify.sh exec -- bash -c 'corepack pnpm -s create:feature order-feature && corepack pnpm exec playwright test tests/e2e/generated-feature.spec.ts'` | 기본 | 20분 | 사본 준비에서 실패 |
|
||||
| X-GD03 | `scripts/verify.sh exec -- bash -c 'systemctl show-environment >/dev/null; echo system=$?; env -u XDG_RUNTIME_DIR -u DBUS_SESSION_BUS_ADDRESS systemctl --user show --property=Version --value; echo user=$?'` | 기본 | 1분 | system=0, user≠0이면 사전 점검(system bus)과 본 단계(user manager)의 판정이 갈리는 호스트 조건이 재현된다 |
|
||||
| X-GD06 | 아래 패치를 얹고 `scripts/verify.sh script verify:documentation --log r9-gd06` | 기본 | 5분 | 지금은 PASS_SCOPED(거짓 통과). 대조로 같은 줄을 `` `node scripts/no-such-script.ts` ``로 바꾸면 FAIL |
|
||||
| X-GD08 | `scripts/verify.sh exec -- bash -c 'corepack pnpm -s create:feature gd08-feature && node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write && rm -r src/features/gd08-feature tests/features/gd08-feature src/contexts/gd08-context docs/accessibility/route-reviews/GD08_LIST.md && corepack pnpm -s generate:feature-index && node scripts/write-dev-release-manifest.ts && node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts'` | 기본 | 15분 | 마지막 명령 rc≠0(기록 drift). 라우트 ID는 생성 출력에서 확인해 고친다 |
|
||||
| X-GD18 | `scripts/verify.sh script check:backend-contract-drift -- --backend $HOME/workspace/clean-architecture-backend-template` | 기본 | 2분 | rc=0이면 pin 뒤 표 변화 없음, 1이면 바뀐 행 출력, 2면 비교 못 함 |
|
||||
|
||||
X-GD01b 패치(`scripts/check-design-system.ts`가 fixture 모드에서 엉뚱한 이유로 exit 1):
|
||||
|
||||
```diff
|
||||
--- a/scripts/check-design-system.ts
|
||||
+++ b/scripts/check-design-system.ts
|
||||
@@ -1,3 +1,4 @@
|
||||
+if (process.argv.includes("--fixture")) { process.stderr.write("unrelated crash\n"); process.exit(1); }
|
||||
import { mkdir, readFile, readdir } from "node:fs/promises";
|
||||
|
||||
import { designSystemReportArtifactSchema } from "./contracts/release-artifacts.ts";
|
||||
```
|
||||
|
||||
X-GD06 패치(살아 있는 문서에 없는 경로·script를 `scripts/verify.sh`·`python3` 명령으로 적는다):
|
||||
|
||||
```diff
|
||||
--- a/docs/work/reference/gates.md
|
||||
+++ b/docs/work/reference/gates.md
|
||||
@@ -112,3 +112,4 @@
|
||||
- 작업 매뉴얼의 분량·이력 ID·뼈대는 `verify:documentation`이 보지 않는다. `scripts/verify.sh docs`가 본다.
|
||||
+- 변이: `scripts/verify.sh exec -- node scripts/no-such-script.ts`, `python3 scripts/no-such-check.py`, `scripts/verify.sh script verify:no-such-docs`.
|
||||
|
||||
## 8. 게이트·검사 스크립트를 더할 때
|
||||
```
|
||||
|
||||
실험마다 작업 폴더를 되돌린다(`scripts/verify.sh`가 새 worktree를 쓰므로 노트북 트리에는 패치만 잠시 얹었다 뺀다).
|
||||
|
||||
## 5. 결함 아님으로 판정한 의심
|
||||
|
||||
- 검사기 음성 fixture와 `check:ci:gating`이 PR에서 돌지 않는다 — 소유자 결정(2026-11-07, `f6b2b96c`). 색인 누락(GD-14)과 안내 누락(GD-05)만 적었다.
|
||||
- `check-typecheck-inputs.ts`가 `tsc --listFilesOnly`의 종료 코드를 보지 않는다 — 같은 `check:types` 사슬에서 모든 project가 먼저 tsc를 통과해야 이 단계에 닿으므로 거짓 PASS 경로가 없다.
|
||||
- `REMOVABLE_TEMPLATE_FEATURES`가 비어 FE-GATE-020의 인자 없는 드릴이 SKIP한다 — 다운스트림용 확장 지점이고 문서(`create-feature.md:161`)가 그렇게 말한다.
|
||||
- `check:remediation-ledger`가 게이트 밖이다 — 이유가 `config/ci/ungated-scripts.json`에 있고, python으로 같은 판정을 흉내 내 보니 지금 통과한다(25행, 열린 행 0, 예산 57,800 일치).
|
||||
- `check-type-fixtures.ts`의 고정 경로 `.tmp/type-fixtures` — 한 checkout 두 실행 문제는 결정 대기 D6(1105)이다.
|
||||
- `docs-system.ts` 머리 주석의 "every pull request" — PR에서는 FE-GATE-005 안의 `documentation-readiness.test.ts`로 돈다. 코드 주석이고 사실과 맞는다.
|
||||
- `scripts/hooks/README.md`의 "막지 않는다"와 N5의 `decision: block` — 같은 문서의 표가 "다음 편집 전까지 한 번"으로 범위를 좁혀 적었다.
|
||||
- `.claude/settings.json` deny가 `.env.<mode>` 중 development·staging·production만 막는다 — 이 repo의 프로필 넷(`local`은 `.env.local`)을 모두 덮는다.
|
||||
- README의 로컬 merge 반복문이 `|| break`로 첫 실패에서 멈춘다 — 제품 팀용 안내이고 다시 돌리는 흐름이다. 소유자 환경의 판정은 `scripts/verify.sh merge`(`gates.md` 3절).
|
||||
- `CHANGELOG.md` 미출시 절의 없는 경로 30여 개 — 모두 지우거나 옮긴 대상을 적은 이력이다(문서 검사도 `HISTORY_HOLDERS`로 뺀다).
|
||||
- `docs/manual/reference/errors.md`의 메시지가 코드에서 글자 그대로 안 나오는 것들 — 템플릿 리터럴로 조립되는 문자열이다(표본 20여 개를 조각으로 대조).
|
||||
- `docs/manual/02-decision-tables.md:448`·`:526`의 백엔드 SHA `45d2a478` — pin과 같다.
|
||||
- 문서에 적힌 `.dependency-cruiser.json` 규칙 이름 — 모두 있다. 문서의 `scripts/verify.sh` 단계·게이트·script 인자 — 노트북 대조에서 모두 있다.
|
||||
- 리뷰어에게 하는 지시가 읽은 코드·문서 안에 있는지 — 찾지 못했다.
|
||||
@@ -0,0 +1,269 @@
|
||||
# round9 L9 — adapter 그룹(http·query-cache·auth·service-worker 밖) 전체 리뷰
|
||||
|
||||
> round9 리뷰(2026-11-12, 대상 main `5250ff95`)의 영역 기록이다. 서브에이전트가 쓴 원문을 그대로 옮겼다. 바꾼 것은 이 인용 블록과, 작업 폴더 절대 경로를 `(작업 폴더)`로 줄인 것뿐이다. 발견 ID는 이 파일의 이름표(R-01 등)이고, 라운드 ID(`1112/NN-MM`)와의 대응은 [README](2026-11-round9-review.md) 15절이다.
|
||||
|
||||
|
||||
대상 커밋 `5250ff95`(origin/main). 읽기만 했다. 코드·테스트를 실행하지 않았다(증거는 모두 E1, 게이트 결과만 desktop 로그를 읽었다).
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- 판정: **고칠 것 있음**. 새 발견 4건이다. 모두 Low이고 High·P1은 없다. 내역은 확인된 결함 2, 구조적 위험 1, 미검증 1이다.
|
||||
- 코드 동작과 계약 문서는 대부분 맞다. 확인한 것: 탭 사이 무효화, OPFS 승인 purge와 partition lock, Cache Storage activation과 rollback 목록, poll·SSE의 오류 분류, Web Push 잠금, 업로드 취소 채널, browser-files dispose, telemetry 전송.
|
||||
- 발견 넷 중 셋은 문서 쪽이다.
|
||||
- 매뉴얼 02 §7 업로드 조립 예가 지난 라운드에 고친 보강 방식을 그대로 가르친다(R-01).
|
||||
- 지금 규칙인 표 둘이 고칠 수 없는 기록 문서에만 있다(R-02).
|
||||
- 계약 문서 한 줄이 "realtime runtime이 없다"고 적는다(R-03).
|
||||
- 나머지 하나는 동시성 시험 공백이다(C-01). 다른 탭의 reconcile과 승인 partition 삭제가 겹치는 경우다.
|
||||
- 지난 라운드에서 넘어온 항목 가운데 이 범위에서 아직 열린 것은 10건이다(2.5절). 그중 결정 대기 5건은 다시 올리지 않았다.
|
||||
|
||||
## 1. 범위
|
||||
|
||||
### 읽은 경로
|
||||
|
||||
- `src/adapters/`의 browser-files, browser-file-storage, browser-rpc, browser-transfer(presigned·resumable-upload·image-cdn과 README), cache-storage, cross-context-invalidation, diagnostics, platform, realtime(sse·websocket·polling·coordinator), storage(Web Storage·indexeddb·opfs), telemetry, web-push.
|
||||
- 줄 단위로 읽은 곳은 아래와 같다. 나머지는 함수 목록과 grep으로 훑었다.
|
||||
- cross-context 전체
|
||||
- `opfs-byte-store-adapter.ts`의 reconcile·enforcePolicies·lock 함수
|
||||
- `opfs-worker-runtime.ts`의 verify·finalize·removePartition·cleanup
|
||||
- `public-response-cache-adapter.ts`의 lookup·stage·activate·cleanup·inspect
|
||||
- `bounded-poll-coordinator.ts`의 lease 루프
|
||||
- `fetch-sse-connection.ts`의 status 분류
|
||||
- `browser-rpc-runtime.ts`의 unary 재시도
|
||||
- `push-subscription-adapter.ts`의 enable·reconcile·revoke·exclusive
|
||||
- `upload-mutation-lock.ts`, `upload-cancellation-channel.ts`
|
||||
- `create-browser-file-runtime.ts`, `storage-manager-adapter.ts`, `abortable-operation.ts`, telemetry 셋, diagnostics
|
||||
- `bbde570..5250ff95`에서 바뀐 곳은 다섯 파일뿐이다: `public-response-cache-adapter.ts`, `bounded-poll-coordinator.ts`, `reconnect-coordinator.ts`, image-cdn `README.md`(번역), `recipes/frontend-capabilities/indexeddb-feature-capability.ts`. 다섯 다 읽었다. README 번역은 원문과 뜻이 같다.
|
||||
- recipe: `recipes/frontend-capabilities/browser-file-session-capability.ts`, `indexeddb-feature-capability.ts`, 그리고 `browser-file-storage-contracts.ts`의 정책 칸.
|
||||
- 문서:
|
||||
- `docs/architecture/optional-adapter-recipes.md` 전체
|
||||
- `docs/manual/02-decision-tables.md` §7 업로드
|
||||
- `docs/manual/03-outside-feature-folder.md` C절
|
||||
- `docs/operations/browser-file-storage-recovery.md` §0·§1·§7
|
||||
- `docs/operations/client-cache-and-storage-recovery.md` 머리·§1~3·§6
|
||||
- `docs/operations/browser-transfer-recovery.md` §1·§4·§6~9
|
||||
- `docs/adr/VD-28` §7·§8
|
||||
- 설계서 `docs/design/2026-07-30-realtime-…` 0.1·6.3·9.2, `docs/design/2026-07-27-browser-file-…` cache activation 절
|
||||
- `src/application/ports/browser-file-storage/{shared,cache-storage-ports}.ts`
|
||||
- `src/application/ports/browser-transfer/resumable-upload.ts`
|
||||
- `src/bootstrap/product-composition-contract.ts`
|
||||
- 짝 백엔드(읽기만): pin `45d2a478`과 HEAD `a7e38c10`의 fileserver 차이를 봤다. 폴더 이동과 번역뿐이다. `UploadedFileResponse`·`FileState`는 그대로이고, 프론트 `uploadedFileSchema`(`fileserver-upload.ts:233-244`)가 DTO 칸과 같다.
|
||||
- 문서가 이름 댄 시험 경로·시험 이름은 모두 있다(`git grep`으로 대조).
|
||||
|
||||
### 쓴 스킬과 그 기준으로 본 것
|
||||
|
||||
- `fe-react`: 함정 1(결과 불명 재전송 입구)을 봤다. 업로드 client, browser-rpc COMMAND, resumable 업로드의 결정적 멱등 키, poll 재시도가 대상이다. 함정 2(status만 보는 분류)는 SSE status 표, poll 결과 대응표, Fileserver 효과 판정으로 봤다. 함정 8(같은 입력 재제출)은 Web Push `busy`, 업로드 lock으로 봤다.
|
||||
- `fe-security`: 함정 13(로그아웃 뒤 남는 저장소 데이터)을 봤다. OPFS 승인 purge, 업로드 checkpoint partition, local-draft recipe 정책, browser-files dispose가 대상이다. 그 밖에 BroadcastChannel 수신 모양 검사(무효화·업로드 취소), telemetry `credentials: "omit"`를 봤다.
|
||||
- SRP·동시성: Web Locks를 쓰는 곳 넷과 BroadcastChannel 둘, 탭 사이 경쟁을 봤다.
|
||||
- Web Locks: OPFS transaction·partition, cache mutation lock, `web-push-control`, 업로드 key lock
|
||||
- BroadcastChannel: 무효화, 업로드 취소
|
||||
- 탭 사이 경쟁: purge와 put·reconcile, stage·activate·cleanup
|
||||
|
||||
### 확인 못 한 것
|
||||
|
||||
- 실행이 필요한 것은 4절 실험 요청으로 냈다(X-L9-01, X-L9-02).
|
||||
- desktop 게이트 `desktop:/tmp/claude-gates/r9fe-base/summary.txt`를 읽었다. 실행한 tree가 HEAD와 같다(`75cc3752`).
|
||||
- FE-GATE-001~012는 rc=0이다.
|
||||
- FE-GATE-013은 rc=1이다. 결정 D8의 호스트 원인인지는 이 로그만으로 모른다.
|
||||
- FE-GATE-020은 아직 결과가 없다. 그래서 recipe 제거 드릴과 browser-file-storage 제거 드릴의 이번 결과는 보지 못했다.
|
||||
- 세부까지 못 읽은 곳: `indexeddb-runtime.ts`(2,641줄), `websocket-connection.ts`의 프레임 처리, `image-cdn-runtime.ts`, `presigned-transfer-executor.ts`, `download-delivery-adapter.ts`. 경계 함수만 grep으로 봤다.
|
||||
- WebKit의 OPFS 동작과, 이전 release 탭과 함께 도는 경우는 이번에도 보지 못했다(1106 README 8절과 같다).
|
||||
|
||||
## 2. 발견
|
||||
|
||||
### R-01 매뉴얼 02 §7 업로드 조립 예가 `declare module`로 capability를 보강한다. 매뉴얼 03과 recipe가 막는 방식이다
|
||||
|
||||
| 칸 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함(같은 저장소의 두 안내가 다르다. 1105/02-03과 같은 모양이고, 고칠 때 남은 사본이다) |
|
||||
| 관련 관점 | 20, 9, 23, 17, 4 |
|
||||
| 심각도·우선순위 | Low·P3. 1105/02-03과 같은 등급이다. 실패는 런타임이 아니라 typecheck에서 드러나고, 맞는 방법은 매뉴얼 03에 있다. 다만 짝 백엔드 업로드라는 기본 짝 경로의 안내이고, 다운스트림이 그대로 복사하는 예다 |
|
||||
| 통제 | M1. 규칙은 매뉴얼 03에 적혀 있다. 이 블록은 `manual-code-block` 표식이 없어 `tests/unit/manual-code-blocks.test.ts`가 시험하지 않는다 |
|
||||
| 증거 | E1 |
|
||||
| 근거 | 아래 목록 |
|
||||
| 발생 조건 | 짝 백엔드 Fileserver 업로드를 붙이는 제품이 §7 "어디에 적나"의 두 블록을 그대로 복사한다 |
|
||||
| 영향 | 매뉴얼 03과 1105/02-03에 따르면, 앱 typecheck는 통과하지만 `check:types:node`가 `fileserverUpload` 키를 보지 못한다. 그래서 기능의 `needs: ["http", "fileserverUpload"]`가 FE-GATE-003에서 실패할 수 있다. 매뉴얼을 그대로 따랐는데 게이트가 실패하는 모양이다(결함 패턴 W3). 실패 여부는 아직 실행하지 않았다(X-L9-01) |
|
||||
| 최소 개선 방향 | 아래 목록 |
|
||||
| 완료 기준 | `git grep -n 'declare module "../features/feature-adapter-contribution.ts"' -- docs/manual`가 0건이다. §7을 그대로 적용한 사본에서 `check:types`(app·node·test)가 통과한다 |
|
||||
| RED 시험 아이디어 | X-L9-01이다. 지금은 §7 블록을 그대로 적용한 사본에서 `check:types:node`가 실패하고(예상), 고친 블록으로는 통과해야 한다. 상시 시험으로 두려면 manual-code-blocks 시험이 node 프로그램까지 돌도록 넓힌다 |
|
||||
|
||||
근거:
|
||||
|
||||
- `docs/manual/02-decision-tables.md:461-472`는 `src/bootstrap/product-composition.ts` 안에 `declare module "../features/feature-adapter-contribution.ts" { interface FeaturePlatformCapabilities { readonly fileserverUpload: … } }`를 쓰라고 한다. `:505`는 기능 쪽 `needs: ["http", "fileserverUpload"]`다.
|
||||
- `docs/manual/03-outside-feature-folder.md:118-119`는 그 타입을 `src/features/product-capabilities.ts`의 `ProductFeaturePlatformCapabilities`에 적으라고 한다. 그리고 "`product-composition.ts` 안에서 `FeaturePlatformCapabilities`를 보강(`declare module`)하면 `check:types:node`가 그 키를 보지 못한다"고 막는다.
|
||||
- `recipes/frontend-capabilities/browser-file-session-capability.ts:24-31`도 같은 규칙이다(1105/02-03 수정).
|
||||
- `src/features/product-capabilities.ts:10-16`, `:28`이 정본이다.
|
||||
- §7 블록은 2026-11-04 `f8005493`에서 썼고, 규칙은 다음 날 정했다. §7만 고치지 않았다. `git grep "declare module" -- docs/manual recipes docs/architecture` 결과에서 이 안내를 하는 곳은 §7 하나다.
|
||||
|
||||
최소 개선 방향:
|
||||
|
||||
- §7 첫 블록을 둘로 나눈다.
|
||||
- `src/features/product-capabilities.ts`: `ProductFeaturePlatformCapabilities`에 `readonly fileserverUpload: FileserverUploadClientDependencies;`를 적는다.
|
||||
- `src/bootstrap/product-composition.ts`: 값만 돌려준다.
|
||||
- 블록에 시험 표식을 다는 것도 고려한다.
|
||||
|
||||
### R-02 지금 규칙인 표 둘이 기록 문서(설계서)에만 있고, 살아 있는 문서와 코드 주석이 그 절을 정본처럼 가리킨다
|
||||
|
||||
| 칸 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 구조적 위험(지금은 표와 코드가 같다. 다음 변경에서 갈라질 자리다) |
|
||||
| 관련 관점 | 9, 17, 23, 26, 4 |
|
||||
| 심각도·우선순위 | Low·P3 |
|
||||
| 통제 | M1. 표는 적혀 있고 코드와 같다. 이 표를 살아 있는 문서와 대조하는 검사는 없고, 고칠 수 있는 자리도 없다 |
|
||||
| 증거 | E1 |
|
||||
| 근거 | 아래 목록 |
|
||||
| 발생 조건 | 다음에 poll 결과 분류(V3 결과 종류가 늘거나 재시도 kind가 바뀜)나 짝 백엔드 실시간 출구가 바뀐다 |
|
||||
| 영향 | 조합 코드 작성자가 따라야 할 표의 유일한 서술이 "지금 동작을 말하지 않는" 문서에 있다. 저장소 규칙상 그 문서를 고칠 수 없어 코드와 갈라진다(결함 패턴 W1·W2) |
|
||||
| 최소 개선 방향 | 두 표를 살아 있는 문서로 옮긴다. 예를 들면 `optional-adapter-recipes.md` 5절 Realtime 아래, poll 표는 `bounded-poll-coordinator.ts`의 `execute` 주석에 표째로 둔다. 코드 주석 `Design 9.2`, `optional-adapter-recipes.md:238`, `docs/manual/03-outside-feature-folder.md:125`는 옮긴 곳을 가리킨다. 설계서 머리 블록의 「현재 정본」에 새 위치를 더한다(머리 블록은 고칠 수 있다) |
|
||||
| 완료 기준 | poll 결과 대응표와 짝 백엔드 실시간 대응표가 `docs/architecture/`(또는 `src` 주석)에 있다. 그 둘을 가리키던 세 곳이 `docs/design/` 절 번호 대신 그 위치를 가리킨다 |
|
||||
| RED 시험 아이디어 | 정적 대조로 본다. `git grep -n "Design 9.2" -- src`와 `git grep -n "realtime-events-web-push-and-bounded-polling-design.md#01" -- docs/architecture docs/manual`가 지금 각 1·2건이고, 고친 뒤 0건이어야 한다. 표 내용은 `tests/unit/realtime/bounded-poll-coordinator.test.ts:1098-1165`의 `pollAttemptResult`가 이미 예로 고정한다 |
|
||||
|
||||
근거:
|
||||
|
||||
- poll 결과 대응표:
|
||||
- 1106/04-02 수정(`6f06e770`, 2026-11-06)이 V3 결과 9종을 poll attempt 결과로 바꾸는 표를 설계서 9.2절에 넣었다(`docs/design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md:1698-1710`).
|
||||
- 1106 README 16.4절은 이것을 "조합 코드가 따를 규칙"이라고 적는다.
|
||||
- 코드 주석이 이 표를 가리킨다: `src/adapters/realtime/polling/bounded-poll-coordinator.ts:120` "Design 9.2 maps each V3 executor outcome to a result."
|
||||
- 짝 백엔드 실시간 대응표:
|
||||
- 1103/04-02 수정이 같은 설계서 0.1절(`:90-160`)에 넣었다. 짝 계약 사실이다.
|
||||
- 살아 있는 문서가 이 절을 가리킨다: `docs/architecture/optional-adapter-recipes.md:235-238`, `docs/manual/03-outside-feature-folder.md:125`.
|
||||
- 그 설계서는 2026-11-08 `99e76e87`에서 `docs/architecture/`(현재 계약)에서 `docs/design/`(기록)로 옮겨졌다.
|
||||
- 머리 블록(`:1-8`)은 "본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다. 현재 정본: `src/adapters/realtime/`"이다.
|
||||
- `.claude/rules/docs.md`는 기록 문서의 본문 수정을 막는다(머리 블록만 고친다).
|
||||
- 결과는 순환이다. 코드는 설계서를 가리키고, 설계서는 코드를 가리킨다.
|
||||
- 반례: 같은 날 옮긴 cache activation 규칙(1106/02-01)은 살아 있는 런북 `client-cache-and-storage-recovery.md:30-35`에도 있어 문제가 없다.
|
||||
|
||||
### R-03 계약 문서가 realtime에 "현재 concrete runtime은 없다"고 적는다. 같은 문서의 표, README, catalog는 참조 runtime이 있다고 적는다
|
||||
|
||||
| 칸 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함(낡은 문장) |
|
||||
| 관련 관점 | 9, 23, 24 |
|
||||
| 심각도·우선순위 | Low·P3 |
|
||||
| 통제 | M0. 상태 문장과 catalog를 대조하는 검사가 없다(`verify:documentation`은 경로와 이름만 본다) |
|
||||
| 증거 | E1 |
|
||||
| 근거 | 아래 목록 |
|
||||
| 발생 조건 | realtime recipe를 고려하는 제품이 5절만 읽는다 |
|
||||
| 영향 | 이미 있는 시험된 reference runtime(`AVAILABLE_NOT_COMPOSED`)을 없는 것으로 알고 새로 쓰거나 도입을 접는다 |
|
||||
| 최소 개선 방향 | 문장을 바꾼다: "reference runtime은 `src/adapters/realtime`(`AVAILABLE_NOT_COMPOSED`)에 있고, 제품 선택과 조립은 없다." 같은 문단의 "detailed status는 설계서를 따른다"도 R-02와 함께 고친다 |
|
||||
| 완료 기준 | 5절 Realtime 문장이 catalog `referenceRuntime.status`와 같은 말을 쓴다 |
|
||||
| RED 시험 아이디어 | 정적 대조로 본다. `git grep -n "현재 concrete runtime" -- docs/architecture`가 0건이어야 한다 |
|
||||
|
||||
근거:
|
||||
|
||||
- `docs/architecture/optional-adapter-recipes.md:234` "현재 concrete runtime과 product selection은 없다"
|
||||
- 같은 문서 `:29`는 "realtime/Web Push/Polling 설계와 reference runtime … `src/adapters/realtime`, `src/adapters/web-push`"라고 적는다.
|
||||
- `README.md:130`은 "`realtime`, … 는 시험한 참조 런타임도 싣지만 기본 빌드는 뺀다"라고 적는다.
|
||||
- `config/recipes/frontend-capability-recipes.json` realtime의 `referenceRuntime.status`는 `AVAILABLE_NOT_COMPOSED`다. README 상태표상 뜻은 "코드와 테스트가 있지만 기본 빌드가 뺀다"이다.
|
||||
- 문장은 runtime을 더한 같은 커밋 `6c52cdb9`(2026-07-30)에서 썼다. 그 뒤 고치지 않았다.
|
||||
|
||||
### C-01 다른 탭의 reconcile과 승인 partition 삭제가 겹치는 경우를 지키는 시험이 없다
|
||||
|
||||
| 칸 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 미검증(코드 경로는 지키는 것으로 읽힌다. 회귀를 막는 시험이 없다) |
|
||||
| 관련 관점 | 12, 11, 10, 5 |
|
||||
| 심각도·우선순위 | Low·P3. 지금 bytes가 남는다는 증거는 없다. OPFS 개인 파일 제품에서는 계정 삭제 약속을 받치는 경로다 |
|
||||
| 통제 | M2. 필요한 코드 경로에 구현됐다. 시험으로는 M0다 |
|
||||
| 증거 | E1 |
|
||||
| 근거 | 아래 목록 |
|
||||
| 발생 조건 | 탭 A가 crash가 남긴 `FILES_READY` row를 reconcile하는 동안, 탭 B가 같은 partition의 승인 LOGOUT·ACCOUNT_DELETION purge로 partition을 지운다 |
|
||||
| 영향 | "`partitionDeleted`면 그 partition의 bytes는 모두 지워졌다"는 약속(런북 §7 `:488-490`)이 이 겹침에서 깨져도 알리는 시험이 없다. 예를 들어 finalize가 디렉터리를 만들게 바뀌거나, reconcile이 commit 뒤 manifest를 다시 쓰게 바뀌어도 그렇다 |
|
||||
| 최소 개선 방향 | 1106 Y3 블록을 시험으로 올리고 worker 단계 hook을 더한다. 멈출 지점은 verify 전, verify 뒤 commit 전, commit 뒤 finalize 전, finalize 뒤 complete 전 넷이다. 다른 방법으로, reconcile도 row마다 partition lock을 shared로 잡으면 put·delete와 순서 규칙이 같아진다. 다만 동작이 바뀐다 |
|
||||
| 완료 기준 | 네 지점 모두에서 `partitionDeleted: true` 뒤 그 partition의 파일이 0이고, 열기가 `NOT_FOUND`이고, journal에 그 partition 키 row가 0이다. 런북 §7 순서 절에 reconcile과의 순서를 한 줄 적는다 |
|
||||
| RED 시험 아이디어 | X-L9-02이다. 변이는 `opfs-worker-runtime.ts` `finalizePut`의 `getDirectory(…, false)`를 `true`로 바꾸는 것이다. 지금은 어떤 시험도 실패하지 않을 것이고(예상), 새 시험에서는 실패해야 한다 |
|
||||
|
||||
근거:
|
||||
|
||||
- reconcile은 transaction lock만 `ifAvailable`로 잡고 partition lock은 잡지 않는다(`src/adapters/storage/opfs/opfs-byte-store-adapter.ts:637-690`, `:1086-1107`).
|
||||
- partition 삭제는 partition lock을 exclusive로 잡지만(`:926-950`, `:1148-1183`), 그 lock은 put·delete만 막는다.
|
||||
- 런북은 put·delete와의 순서만 적는다(`docs/operations/browser-file-storage-recovery.md:495-510`).
|
||||
- 1106 05 영역은 `commitPut` 앞·뒤 두 지점만 실험(Y3, 시험에 넣지 않음)했다. `verifyObject`·`finalizePut` 도중은 미검증으로 남겼다(`docs/reviews/2026-11-06-maturity-review/05-adapters-storage-kernel.md:145`).
|
||||
- `git log bbde570..HEAD -- tests/unit/opfs-worker-runtime.test.ts`는 0건이다. 그 시험 파일의 reconcile 겹침 시험(`:2047`)은 put·delete와의 겹침이다.
|
||||
- 코드 읽기로는 bytes를 다시 만들지 않는다.
|
||||
- worker `finalizePut`은 디렉터리를 `create: false`로 열고, NotFound면 staging 정리만 한다(`opfs-worker-runtime.ts:951-990`, `:900-925`, `:1559-1570`).
|
||||
- `verifyObject`는 NotFound를 `false`로 읽는다(`:701-735`).
|
||||
- journal `removePartition`은 commit된 row까지 키로 지운다.
|
||||
|
||||
### 2.5 이월 항목 재확인(이 범위, `5250ff95`)
|
||||
|
||||
1106 README 13.4절에서 이 범위에 열려 있던 것이다. 새로 세지 않았고 지금 상태만 적는다.
|
||||
|
||||
| ID | 지금 상태 | 근거 |
|
||||
|---|---|---|
|
||||
| 1105/02-02 남은 부분 | 남음 | 읽히지 않는(손상이 아닌) release marker를 stage가 다시 쓰지 않고 실패를 돌려준다(`public-response-cache-adapter.ts:463-469`). 1106/02-01은 pointer만 풀었다 |
|
||||
| 0929/05-01 ③ | 남음 | 손상된 chunk reference row 하나가 `isChunkReferenced`를 `CORRUPT_DATA`로 끝낸다(`indexeddb-opfs-journal.ts:829-862`). orphan GC가 reconcile마다 가장 낮은 digest부터 다시 돌아 그 row에서 계속 멈춘다(`opfs-byte-store-adapter.ts:698-704`) |
|
||||
| 1101/05-06 | 일부 | `__proto__`류 키 거절(W5)과 accessor 거절(W6)을 보는 시험이 없다. Web Storage를 직접 부르는 시험은 여전히 `tests/unit/storage-registry.test.ts` 하나다. W4(Firefox quota 이름)는 시험이 있다(`:59`) |
|
||||
| 0929/01-03 | 일부 | 업링크 기본값 64 KiB가 세 곳에서 두 곳으로 줄었다(`runtime-policy.ts:79`, `fileserver-upload.ts:165`). 값은 아직 같다 |
|
||||
| 1101/01-03 | 남음 | `partBufferCopyFactor`가 설정값이다(`runtime-policy.ts:12`, `:68`) |
|
||||
| 0929/01-04 | 남음 | `REQUIRED_ABORT_CONSUMERS`가 네 파일을 이름으로 고정한다(`scripts/check-adapter-inventory.ts:140-145`). 주석이 래칫 의도를 적는다 |
|
||||
| 0929/01-05 | 남음 | `upload()`의 recovery 표는 있다(`resumable-upload.ts:104-126`). `abort()`의 표는 없다(`:131-134`) |
|
||||
| 0929/02-03 | 남음 | 0.2.0 절의 browser-files [계약] 행이 경로를 `src/adapters/browser-file-storage/`로 적는다(`CHANGELOG.md:624`). 출시된 절이다 |
|
||||
| 1105/01-02 남은 부분 | 일부·백엔드로 넘김 | Fileserver code 표가 drift 검사 밖이다(`scripts/check-backend-contract-drift.ts`에 fileserver 0건) |
|
||||
| 결정 대기 1101/02-02, 0929/02-02, 0929/02-06, 0929/04-02, 0929/04-03 | 결정 대기 | 다시 올리지 않는다 |
|
||||
|
||||
## 3. 넘길 것
|
||||
|
||||
- → 총괄·문서 담당: R-02와 같은 모양이 다른 설계서에도 있는지 본다. 2026-11-08 이동으로 지금 규칙이 기록 문서에만 남은 곳이 더 있을 수 있다. 이 렌즈는 realtime 둘만 봤다. 코드 주석의 `design N.N` 참조 7곳(`git grep -nE "(Design|design) [0-9]+\.[0-9]+" -- src/adapters/realtime`)은 대부분 근거 설명이고 따를 규칙이 아니라서 세지 않았다.
|
||||
- → 총괄(FE-GATE-013): 이번 `summary.txt`의 rc=1이 결정 D8의 호스트 원인인지 `scripts/verify.sh parts FE-GATE-013`의 뒤 명령 rc로 확인한다. 이 리뷰 범위의 판정은 아니다.
|
||||
- → 백엔드 repo 세션(총괄 경유): 1106/01-01과 1105/01-02의 요청이 그대로다. 202 `REJECTED`의 이유 code와 Fileserver code 표의 pin 대조가 대상이다. 백엔드 HEAD `a7e38c10`은 pin `45d2a478` 뒤로 fileserver를 폴더만 옮겼다(`1388c06a`). 프론트 문서는 pin 경로(`src/application-fileserver/`)를 적으므로 지금 틀리지 않다. pin을 옮길 때 경로도 같이 고쳐야 한다.
|
||||
|
||||
## 4. 실험 요청
|
||||
|
||||
### X-L9-01 (R-01) — §7 조립 예를 그대로 적용하면 `check:types:node`가 실패하는가
|
||||
|
||||
- 명령:
|
||||
- `scripts/verify.sh exec -- bash -lc 'corepack pnpm create:feature attachment-feature && git apply /tmp/l9-x01.patch && corepack pnpm check:types; echo rc=$?'`
|
||||
- 고친 안: 같은 기능에서 `/tmp/l9-x01-fixed.patch`를 적용하고 같은 명령을 돌린다.
|
||||
- env: 없음(local).
|
||||
- 시간 상한: 15분. 끝나면 checkout을 되돌린다(restore=clean).
|
||||
- 패치 내용(수정 담당이 만든다. 이 리뷰는 파일을 쓰지 않았다):
|
||||
- `l9-x01.patch`
|
||||
- `docs/manual/02-decision-tables.md:461-494`의 `product-composition.ts` 블록을 그대로 `src/bootstrap/product-composition.ts`에 넣는다.
|
||||
- `PRODUCT_REST_AUTH_PROFILES`에는 `BACKEND_SESSION`이 없다. 그래서 `authProfile`은 템플릿 `ANONYMOUS` 프로필로 바꾸고, `credentialProviders`는 비운다.
|
||||
- 생성 기능의 `adapters/create-attachment-feature-input.ts`에 `:500-514` 블록대로 `needs: ["http", "fileserverUpload"]`와 `createFileserverUploadClient(fileserverUpload)` 호출을 넣는다.
|
||||
- `l9-x01-fixed.patch`
|
||||
- `declare module` 대신 `src/features/product-capabilities.ts`의 `ProductFeaturePlatformCapabilities`에 `readonly fileserverUpload: FileserverUploadClientDependencies;`를 적는다.
|
||||
- 기대:
|
||||
- 앞의 것은 `check:types:app` 통과, `check:types:node` 실패(키 없음), rc≠0이다.
|
||||
- 고친 것은 rc=0이다.
|
||||
- 앞의 것이 rc=0이면 R-01의 영향은 "안내가 서로 다름"으로 낮춘다. 성격은 그대로 확인된 결함이다.
|
||||
|
||||
### X-L9-02 (C-01) — reconcile과 승인 partition 삭제의 겹침, worker 단계 네 지점
|
||||
|
||||
- 명령: `scripts/verify.sh exec -- node scripts/run-vitest.ts run tests/unit/opfs-worker-runtime.test.ts`
|
||||
- env: 없음.
|
||||
- 시간 상한: 10분.
|
||||
- 패치: 1106 실험 `05-R1.patch`의 Y3 블록(`desktop:/tmp/claude-gates/r5/…`, 요청 파일 `scratchpad/r5/requests/05.md`)을 바탕으로 한다.
|
||||
- reconcile을 멈추는 지점을 넷으로 늘린다: verify 전, verify 뒤 commit 전, commit 뒤 finalize 전, finalize 뒤 complete 전.
|
||||
- 각 지점에서 다른 탭 역할의 adapter가 승인 ACCOUNT_DELETION purge를 끝낸 뒤 reconcile을 풀어 준다.
|
||||
- 단언은 셋이다: `partitionDeleted: true`, 그 partition의 파일 0(삭제 전에 한 번 세서 0이 아님을 대조), 열기 `NOT_FOUND`.
|
||||
- 변이 실행: 같은 패치에 `src/adapters/storage/opfs/opfs-worker-runtime.ts` `finalizePut`의 `getDirectory(…, false)`를 `true`로 바꾸는 변이를 더해 한 번 더 돌린다.
|
||||
- 기대:
|
||||
- 변이 없으면 네 지점 모두 통과한다.
|
||||
- 변이에서는 적어도 "commit 뒤 finalize 전" 지점이 실패한다.
|
||||
- 변이 없이도 실패하는 지점이 있으면 C-01을 확인된 결함으로 올리고 등급을 다시 매긴다(OPFS 개인 파일 제품 P1 후보).
|
||||
|
||||
## 5. 결함 아님으로 판정한 의심
|
||||
|
||||
- 탭 사이 무효화가 release마다 다른 `cacheEpoch`라 옛 탭과 새 탭이 hint를 주고받지 않는다. 의도된 동작이다. `crossContextCacheEpochForRelease`(`browser-cross-context-host.ts:38-50`)와 런북 2절 6이 그렇게 적고, hint일 뿐이라 focus refetch가 남는다.
|
||||
- 무효화 storage 경로에 `DEGRADED_STORAGE_FALLBACK` 탭이 있다. 이 탭은 다른 탭의 broadcast를 못 받는다. 상태 주석과 런북 2절 3이 그대로 적는다. 다른 탭은 늘 storage listener를 단다(`browser-cross-context-invalidation.ts:214`, `:240-256`). 수신은 storage event도 `storageArea`를 객체 identity로 확인하고 wire parser를 거친다.
|
||||
- Cache Storage에서 다른 탭의 `cleanupOwned`가 stage 뒤 activate 전의 후보를 지울 수 있다. 그래도 activation이 `NOT_FOUND`·`REHYDRATE`로 닫히고 잘못된 pointer를 쓰지 않는다(`public-response-cache-adapter.ts:648-660`, `NOT_FOUND`은 `:656`). 설계서도 cleanup은 pointer가 보존하는 것 밖을 지운다고 적는다.
|
||||
- `replaceUnreadablePointer`는 일시 오류에서도 pointer를 덮어 rollback 목록을 잃는다. 호출자가 고르는 옵션이고, 포트 주석(`cache-storage-ports.ts:98-108`)과 런북 `:30-35`가 같은 결과를 적는다.
|
||||
- SSE 500은 `PROTOCOL_MISMATCH`이고 재시도하지 않는다. poll은 5xx를 재시도한다. SSE 상태 표(설계 6.3, VD-28 §7)는 502·504만 hint 없이 재시도하고, 표 밖은 닫는다고 적는다. 코드도 같다(`fetch-sse-connection.ts:589-623`). 전송마다 일부러 다르게 정한 것이다.
|
||||
- browser-rpc COMMAND가 transport에 닿은 뒤 실패하면 늘 `MAYBE_APPLIED`가 된다(`browser-rpc-runtime.ts:303-310`). `KEYED_COMMAND`는 같은 키가 있을 때만 다시 보낸다(`:1513-1528`). 결과 불명 재전송 입구가 아니다.
|
||||
- resumable 업로드의 재시도는 `deriveUploadIdempotencyKey`로 만든 같은 키를 쓴다(`resumable-upload-runtime.ts:650-672`, `:927-985`).
|
||||
- Web Push `revoke`·`revokeForeign`은 Web Locks가 없어도 잠금 없이 돈다. `enable`·`reconcile`이 lock 없으면 `PUSH_UNSUPPORTED`(`push-subscription-adapter.ts:605-608`)라 그 환경에서는 association이 생기지 않는다. 로그아웃 정리는 막히면 안 된다. 같은 탭의 겹친 호출은 `BUSY`다.
|
||||
- 업로드 취소 BroadcastChannel은 키 두 개를 정확히 맞추고, protocol과 `SAFE_UPLOAD_KEY`를 확인한다(`upload-cancellation-channel.ts:184-213`). 정확성은 Web Lock·CAS·백엔드 멱등성이 지킨다고 주석이 적는다.
|
||||
- local-draft IndexedDB recipe는 drafts를 `ORIGIN_SHARED`·`KEEP_ORIGIN_SHARED`로 로그아웃 뒤에도 남긴다(`indexeddb-feature-capability.ts:40`, `:55-67`). 그래도 결함이 아니다.
|
||||
- 정책 검사기가 허용하는 조합이다(`shared.ts:272-282`). `PERSONAL`·`CONFIDENTIAL`은 `OPAQUE_PARTITION`이어야 한다는 규칙은 있다.
|
||||
- recipe가 "정책은 제품 결정으로 바꾼다"고 적는다.
|
||||
- 템플릿은 이것을 조립하지 않는다.
|
||||
- 업로드 checkpoint DB는 partition 이름을 갖고 `deletePartition`이 있다(`indexeddb-checkpoint-store.ts:170-180`, `:455-490`). 런북 §1의 "account partition 안에서만 보존"과 맞는다.
|
||||
- browser-files dispose는 picker·download·preview·object URL registry·vault를 모두 닫는다(`create-browser-file-runtime.ts:177-189`). 세션 recipe가 scope participant로 부른다.
|
||||
- `requestPersistence`는 user activation 객체를 한 번 잡지만 `isActive`는 호출 때마다 읽는다. 살아 있는 객체라 문제없다.
|
||||
- telemetry 전송은 `credentials: "omit"`, `cache: "no-store"`이고, keepalive 예산이 있다(`telemetry-collector.ts:120-150`). diagnostics는 projection을 거쳐서만 기록한다.
|
||||
- 파일이 큰 adapter가 여럿이다(1,700~2,600줄 8개). 크기만으로는 결함이 아니다(`review-criteria.md` 2절 끝 문단).
|
||||
- image-cdn README 번역(`bbde570` 뒤 유일한 큰 변경)은 원문과 뜻이 같다(구절별로 대조했다).
|
||||
- Fileserver 업로드 응답 schema는 짝 백엔드 DTO와 칸이 같다. pin과 HEAD 둘 다다(`fileserver-upload.ts:233-244`, 백엔드 `UploadedFileResponse.java:11-29`).
|
||||
- OPFS lock 대기 기본값 10분, put idle 2분은 런북과 코드가 같다(`opfs-policy.ts:68-69`).
|
||||
- 읽은 코드·문서 안에 리뷰어에게 하는 지시는 없었다.
|
||||
@@ -0,0 +1,267 @@
|
||||
# round9 PA — 지난 발견 재판정 (입력 A, 58행)
|
||||
|
||||
> round9 리뷰(2026-11-12, 대상 main `5250ff95`)의 영역 기록이다. 서브에이전트가 쓴 원문을 그대로 옮겼다. 바꾼 것은 이 인용 블록과, 작업 폴더 절대 경로를 `(작업 폴더)`로 줄인 것뿐이다. 발견 ID는 이 파일의 이름표(R-01 등)이고, 라운드 ID(`1112/NN-MM`)와의 대응은 [README](2026-11-round9-review.md) 15절이다.
|
||||
|
||||
|
||||
리뷰어 PA. 현재 커밋 `5250ff95`(tree `75cc3752`). 읽기만 했다. 실행 증거는 총괄의 desktop merge 단계(`desktop:/tmp/claude-gates/r9fe-base/summary.txt`, 같은 tree)뿐이다.
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- 58행 재판정: **고쳐짐 18 · 일부 17 · 남음 23 · 재발 0 · 틀린 발견 0 · 해당 없음 0**(행 안의 일부가 해당 없음이 된 것은 그 행에 적었다).
|
||||
- 붙은 표시: 결정 대기(색인에 열림) 2(1103/03-07 D3, 1103/09-04 D2) · **결정 대기(색인 없음) 7** · 백엔드로 넘김 5 · 실행 환경 대기 4.
|
||||
- **새로 본 것 둘.**
|
||||
- PA-01: 정리 2단계 `e3c8db48`이 참조 기능을 지우면서 1106/08-01·DR-03·FR-01(다시 마운트한 폼) 시험을 옮기지 않고 지웠다. 공용 `use-app-form.ts:234-249` 분기를 지키는 시험이 없다. 그래서 1106/08-01은 「고침」에서 「일부」로 내린다.
|
||||
- PA-02: 「결정 대기」로 남은 7행이 결정 색인 `docs/work/reference/decisions.md:77-87`(3.1절)에 없다. 그 문서 3절 규칙대로면 「결정 대기가 아니라 미완」이다.
|
||||
- 1105·1106에서 「남김」으로 둔 잔여 둘(FR-03, 폼 밖 `submit`의 retry-later)이 그대로다. 1106/03-01의 완료 기준은 지금도 성립한다.
|
||||
- 고칠 대상은 결정 대기가 아닌 남음·일부·잔여 **31건**이다(Medium·P1 1, Medium·P2 2, 나머지 Low). 그 밖에 PA-02 정리 1건. 목록은 3절 끝.
|
||||
|
||||
## 1. 범위
|
||||
|
||||
- 읽은 것:
|
||||
- 입력 `prior-A.md` 58행. 원문은 `docs/reviews/2026-11-06-maturity-review/` 01~09 영역 문서와 README 13.4·16절, 1105 README 7·16절, 1101 README 5·13.5·14절, 0929 README 5절, 0929·1101·1103 영역 문서의 해당 절, `2026-09-25-maturity-review/FOLLOW-UP.md`.
|
||||
- 지금 코드: 각 행의 파일. 옮겨진 파일은 `git diff --name-status -M bbde570 5250ff95`로 찾았다. 설계서는 `docs/design/`, VD는 `docs/adr/`, local-draft는 `tests/fixtures/indexeddb-consumer/`로 갔다. 참조 기능·예제 화면은 `e3c8db48`에서 지워졌다.
|
||||
- 결정 색인 `docs/work/reference/decisions.md`, 기준 `docs/work/reference/review-criteria.md` 2·3·5·6절, `.claude/agents/reviewer.md`.
|
||||
- 짝 백엔드: pin `45d2a478`과 지금 main `a7e38c10`(238커밋 뒤)을 함께 봤다. 「백엔드로 넘김」이 백엔드에서 풀렸는지 확인하려고 봤다.
|
||||
- 쓴 기준: `review-criteria.md` 6절(「고침」도 코드로 다시 본다, 완료 기준 실행이 없으면 「일부」). 2절 「결함으로 보지 않는 것」(bulk `results` 등).
|
||||
- 실행 증거: 총괄 desktop 실행(`5250ff95`과 같은 tree, CI env)이다.
|
||||
- FE-GATE-001~012 rc=0. FE-GATE-013 rc=1이다. D8 결정에 따라 호스트 원인으로 본다.
|
||||
- FE-GATE-020은 읽을 때 아직 돌고 있었다.
|
||||
- 게이트 로그는 PASS 한 줄뿐이라 시험 이름별 결과는 못 봤다. 「고쳐짐」 행의 실행 증거는 그 시험 파일이 그 게이트에 들어 있다는 정적 확인에 기댄다(E1~E2).
|
||||
- 확인 못 한 것:
|
||||
- FE-GATE-020 결과. 07-02는 템플릿 상태에서 대상 스키마가 0개라, 생성 기능을 넣은 이 드릴에서만 실제로 검사된다.
|
||||
- 브라우저 동작(06-01 실제 redirect 등록, 08-03 Firefox·WebKit).
|
||||
- 짝 백엔드 실연동(업로드, Keycloak·Redis).
|
||||
|
||||
## 2. 상태 표
|
||||
|
||||
열 뜻: 「11-06」은 입력의 상태다. 「지금」은 `5250ff95`에서 본 상태다. 등급은 남은 부분의 지금 등급이다.
|
||||
|
||||
| ID | 11-06 상태 | 지금 상태 | 근거 `file:line` | 남은 것·지금 등급 | 고칠 방향 |
|
||||
|---|---|---|---|---|---|
|
||||
| 1105/01-02 | 일부 · 백엔드로 넘김 | **일부 · 백엔드로 넘김** | `src/adapters/http/fileserver-upload.ts:194-199`(`TRANSFER_TIMEOUT` 없음 유지), `config/contracts/backend-contract-pin.json:44`(readers 하나), `scripts/check-backend-contract-drift.ts`(Fileserver 0건), 백엔드 main `BlockingTransferExecutor.java:72-79`(pin과 같음) | 프론트 몫: Fileserver code 표(`NOT_APPLIED_5XX_CODES`)·202 state 해석이 pin 대조 밖이다. Low·P3(구조적 위험, 손 사본이 아직 같음). 백엔드 몫(ambiguous 표시·`Idempotency-Key`)은 main에서도 그대로다. 커밋 `471b001` 본문 (b)는 올린 이력이라 고치지 않는다 | pin에 Fileserver 출처 행을 더하고 readers에 `fileserver-upload.ts`를 넣는다 |
|
||||
| 1105/02-02 | 일부 | **일부** | `src/adapters/cache-storage/public-response-cache-adapter.ts:463-468`, `src/application/ports/browser-file-storage/cache-storage-ports.ts:66-71`, `docs/operations/client-cache-and-storage-recovery.md:18-34`(marker 절차 없음) | 계속 읽히지 않는 release marker를 stage가 다시 쓰지 않는다. 포트 주석이 "lookup 실패도 다시 stage가 고친다"고 넓게 적는다. Low·P3 | marker도 entry처럼 같은 manifest stage에서 다시 쓴다(지우지 않음). 주석에서 "or lookup"을 뺀다 |
|
||||
| 1105/03-02 | 고쳐짐 · 백엔드로 넘김 | **고쳐짐 · 백엔드로 넘김** | `src/adapters/http/backend-envelope.ts:191-192`, 계약 `docs/architecture/backend-api-and-server-state-contract.md:340-343`, 백엔드 main `RateLimitInterceptor.java`(dispatcher 종류를 안 봄) | 비동기 재디스패치 위험은 백엔드 몫 그대로 | — |
|
||||
| 1105/06-02 | 일부 · 결정 대기 | **일부 · 결정 대기(색인 없음)** | `scripts/lib/hosting-probe.ts:300`, `:339-344` | 워커 없는 빌드에도 자산 probe가 돌고, 이유 문구가 워커를 든다. 빈 `distFiles` 실수는 아무 검사도 잡지 않는다. Low·P3 | 결정을 3.1절 형식으로 올린다(PA-02) |
|
||||
| 1103/01-01 | 일부 · 백엔드로 넘김 | **일부 · 백엔드로 넘김 · 실행 환경 대기** | 백엔드 main `docs/fileserver/http-contract.md:9`("`202` VERIFYING"만), `docs/manual/03-placement.md:27`(모듈 이름만) | 프론트 몫 끝. 백엔드 문서 둘이 main에서도 그대로다. 실제 짝 업로드를 안 돌렸다 | — |
|
||||
| 1103/03-01 | 일부 · 결정 대기 | **일부 · 결정 대기(색인 없음)** | (2) `src/presentation/adapters/query/application-query.ts:904-913`(`canResend`가 원인을 안 봄), `backend-envelope.ts:282-287`. (3) `src/presentation/forms/use-app-form.ts:265-284`, 시험 `tests/component/form-foundation.test.tsx:1050-1079`, `docs/adr/VD-04-native-form-facade.md:35` | (1) 참조 폼이 지워져 거짓 "저장했습니다."가 템플릿 경로에서는 안 보인다. 생성 폼은 확인 뒤 목록으로 간다(`scripts/create-feature-write-slice.ts:733-739`). 공용 facade 동작은 그대로다. (2) `RECOVERY_REQUIRED` 뒤 재전송 버튼: 결정 대기. (3) 선언한 409를 `validation-error`로 보이는 동작이 VD-04 결정 5와 어긋나고, VD-04에 보완 절이 없다. Low·P3 | (3) VD-04에 날짜 붙은 「보완」 절을 단다(`docs/README.md:114` 규칙). (2)는 PA-02 |
|
||||
| 1103/03-02 | 일부 · 결정 대기 | **고쳐짐** | `meta.page`: `backend-envelope.ts:112-126`. bulk 비지원: 계약 `:192-198`, `docs/work/reference/review-criteria.md:43`("bulk `results`"는 결함 아님) | 남은 bulk는 지원 범위 밖으로 적혀 있어 결함이 아니다 | — |
|
||||
| 1103/03-07 | 일부 · 결정 대기 | **일부 · 결정 대기 D3(열림)** | 백엔드 main `__Feature__Controller.java.tmpl:49`, `:63`(POST, `GET /{id}`만), `scripts/create-feature.ts:769`, `decisions.md:85` | 그대로 | D3 결정 뒤 |
|
||||
| 1103/09-03 | 일부 · 백엔드로 넘김 | **일부 · 백엔드로 넘김 · 실행 환경 대기** | 백엔드 main `compose/keycloak/realms/ca-skeleton-realm.json`(client `ca-skeleton-api` 하나, confidential) | 그대로 | — |
|
||||
| 1103/09-04 | 일부 · 결정 대기 | **일부 · 결정 대기 D2(열림)** | `src/contracts/routes.ts:33`, `/examples/platform`을 쓰는 spec 7개(`tests/e2e/{accessibility,old-tab-chunk-recovery,platform-overview,responsive,scroll-restoration,typography}.spec.ts`, `tests/visual/platform.visual.spec.ts`), `decisions.md:84` | 지울 수 있던 예제 3화면은 `e3c8db48`에서 지워져 그 부분은 해당 없음. 플랫폼 구성 화면은 D2 | D2 결정 뒤 |
|
||||
| 1103/09-05 | 일부 | **일부** | `src/bootstrap/product-composition-contract.ts:127-139`(blockers·observe만), `src/contracts/service-worker.ts:177`, `:190`(쓰는 곳 0), `src/bootstrap/optional-runtime-host.ts:63` | 활성화 화면·reload 안내를 이을 제품 소유 자리가 없다. realtime·worker·offline은 템플릿 파일 수정 안내로 거절된다. Medium·P2(원래 등급) | `ProductServiceWorkerWiring`에 `onUpdateWaiting`·`onReloadRequired`를 받는 칸을 열거나 presentation 슬롯 하나 |
|
||||
| 1103/04-01 | 고쳐짐 | **고쳐짐** | `src/application/policies/bounded-polling.ts:130`, `src/adapters/realtime/polling/bounded-poll-coordinator.ts:112-114` | 조합 코드가 `input.operation`을 무시하는 잔여 위험은 문서화돼 있다(원래 완료 기준 밖) | — |
|
||||
| 0929/02-02 | 일부 · 결정 대기 | **일부 · 결정 대기(색인 없음)** | `cache-storage-ports.ts:122`(signal 없음), `:66-71`(판정 불가 = `false`) | 그대로. Low·P3 | PA-02 |
|
||||
| 1101/02-02 | 일부 · 결정 대기 | **일부 · 결정 대기(색인 없음)** | `src/adapters/browser-files/browser-file-policy-registry.ts:447-456` | media type·확장자 짝을 안 본다. Low·P3 | PA-02 |
|
||||
| 0929/02-06 | 남음 · 결정 대기 | **남음 · 결정 대기(색인 없음)** | `.dependency-cruiser.json:261`, 쓰는 곳 `src/adapters/query-cache/tanstack-cache-coordinator.ts:18-21`(`import type` 하나), `AGENTS.md` 꼭 지킬 것 2 | 루트 규칙이 이 예외를 kernel로 적어, 바꾸려면 소유자 결정이 필요하다. Low·P3 | PA-02 |
|
||||
| 0929/04-02 | 남음 · 결정 대기 | **남음 · 결정 대기(색인 없음)** | `src/adapters/realtime/sse/fetch-sse-connection.ts:498`(`readSseForReconnect` 하나). SSE 폴더 diff 0줄 | Medium·P2(원래 등급) | PA-02 |
|
||||
| 0929/04-03 | 남음 · 결정 대기 | **남음 · 결정 대기(색인 없음)** | `src/adapters/realtime/sse/sse-parser.ts:330-341` | 그대로. 설계서는 이제 기록 문서(`docs/design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md`)다. Low·P3 | PA-02 |
|
||||
| 1101/01-03 | 남음 | **남음** | `src/adapters/browser-transfer/resumable-upload/runtime-policy.ts:12`, `:68`, `:101-107` | copyFactor가 설정값이고 하한이 1이다. Low·P3 | 구현 상수 `PART_BUFFER_COPIES` 하한 |
|
||||
| 0929/01-03 | 남음 | **남음** | `runtime-policy.ts:79`, `presigned/presigned-transfer-executor.ts:141-142`, `src/adapters/http/fileserver-upload.ts:164-165`, 안내는 기록 문서 `docs/design/2026-07-30-presigned-transfer-and-image-cdn-design.md:315` | 64 KiB/s가 세 곳에 따로 있다. 살아 있는 안내가 없다. Low·P3 | 정책 주석과 레시피 문서에 "실행기 값도 함께 낮춘다"를 적거나, 실행기가 정책 값을 받게 한다 |
|
||||
| 0929/01-04 | 남음 | **남음** | `scripts/check-adapter-inventory.ts:140-145`, `scripts/contracts/release-artifacts.ts:1182` | 파일 이름 고정과 원인 없는 ZodError가 그대로다. Low·P3 | 없는 파일은 건너뛰고, 레시피 경로 없음을 이름으로 보고한다 |
|
||||
| 0929/01-05 | 남음 | **남음** | `src/application/ports/browser-transfer/resumable-upload.ts:104-130`(표는 `upload()`만), `resumable-upload-runtime.ts:238-245` | `abort()` 실패의 행동 표가 없다. Low·P3 | 포트 주석에 `abort()` 표를 더하고 번역을 둔다 |
|
||||
| 0929/02-03 | 남음 | **남음** | `CHANGELOG.md:624` | 0.2.0 browser-files 행 경로가 `src/adapters/browser-file-storage/`다(실제는 `src/adapters/browser-files/`). Low·P3 | 처음부터 틀린 문장이라 고친다(1106 README 16.4 끝의 예외 규칙) |
|
||||
| 1101/03-04 | 남음 | **남음** | `backend-envelope.ts:363`, `:401`. 폼 순서 `use-app-form.ts:286-311`(`VALIDATION_REJECTED`가 `MAYBE_APPLIED`보다 먼저). 생성 폼 `create-feature-write-slice.ts:674`, `:722-747`. 고정 시험 `form-foundation.test.tsx:1131` | `MAYBE_APPLIED`이면서 필드 오류인 실패에서 필드 오류와 결과 불명 화면이 같이 뜬다. Low·P3 | 폼이 효과를 먼저 본다. 바인딩 조합 진단 |
|
||||
| 0929/03-02 | 남음 | **남음** | `docs/runbooks/FE-RB-003.md:1-12`(CORS 없음), `docs/operations/api-contract-and-server-state-recovery.md:184-189`(설명만, 점검 명령 없음) | 0929 권고 (가)의 runbook·점검 명령이 없다. **등급 조정 Medium·P2 → Low·P3**: 짝 백엔드 기본값이 `allowed-headers: ${APP_SECURITY_CORS_ALLOWED_HEADERS:*}`다(백엔드 `src/bootstrap/app/src/main/resources/config/security.yml:50`, pin `CorsSettings.java`도 `*`) | FE-RB-003 첫 분류에 CORS, 배포 절차에 preflight `curl` 한 줄 |
|
||||
| 0929/05-01 | 일부 | **일부** | `src/adapters/storage/opfs/indexeddb-opfs-journal.ts:855-861`, `opfs-byte-store-adapter.ts:1396` | ③ 손상 chunk reference 행 하나가 reconcile·GC를 멈춘다. purge는 영향 밖이라 **Low·P3로 낮춘다**. 1101 14.1 결정("손상 행은 건너뛰고 수를 보고한다")과 어긋난다 | 손상 reference를 "참조됨"으로 보고 chunk를 남긴 채 센다 |
|
||||
| 1101/05-06 | 일부 | **일부** | `src/adapters/storage/browser-storage-adapter.ts:120-125`, `browser-storage-codec.ts:202-206`, `git grep browser-storage-codec -- tests` 0건 | W2·W5·W6 시험이 없다. Low·P3 | 시험 셋 |
|
||||
| 0929/05-05 | 남음 | **남음** | `src/adapters/storage/indexeddb/indexeddb-runtime.ts:2580-2586` | Low·P3 | 계정 삭제는 `INCOMPATIBLE`에서도 전체 삭제를 쓴다 |
|
||||
| 0929/05-06 | 남음 | **남음** | `indexeddb-runtime.ts:97`(`{16,128}`), `opfs-byte-store-adapter.ts:1930`(`{16,512}`) | Low·P3 | `src/adapters/platform/` 상수 하나 |
|
||||
| 0929/05-07 | 남음 | **남음** | `stableJson` `opfs-prepared-object.ts:138`, `public-cache-codec.ts:637`; `canonicalJson` `realtime/event-codec.ts:414`; `sameScope` `indexeddb-opfs-journal.ts:1428`, `opfs-worker-runtime.ts:1690` | 갈라질 수 있는 사본(지금은 같음). Low·P3 | `src/adapters/platform/`로 모은다 |
|
||||
| 0929/05-10 | 남음 | **남음** | `indexeddb-opfs-journal.ts:131`, `indexeddb-governance.ts:83` | Low·P3 | 접두사를 조립 옵션으로 |
|
||||
| 0925/06-05 | 일부 | **일부** | `src/adapters/service-worker/service-worker-page-controller.ts:335-359`(`installed`만, `.catch(() => {})`), `src/bootstrap/optional-runtime-host.ts:28`(`health()` 읽는 곳 0) | 업데이트 설치 실패·주기 검사 실패가 observe·telemetry에 없다. Low·P3 | `redundant`·`update()` 실패를 observe 이벤트로 낸다 |
|
||||
| 0925/06-08 | 남음(영향 넓어짐) | **남음** | `src/contracts/service-worker.ts:119-126`, `vite.config.ts`(`assetsDir` 없음), `config/hosting/cache-policy.json:26` | `assetsDir`를 바꾸면 fallback·probe·사전 캐시가 조용히 빈다. Low·P3 | `vite.config.ts`가 상수에서 `build.assetsDir`를 정하거나, 시험이 둘을 대조한다. 빈 manifest를 거절한다 |
|
||||
| 0925 P3 | 남음 | **남음** | `tests/e2e/service-worker-update.spec.ts:54-72` | Low·P3 | 도우미 옵션 |
|
||||
| 1101/06-03 | 남음 | **남음** | `src/adapters/service-worker/service-worker-protocol.ts:16`, `:18`, `src/contracts/service-worker.ts:27-28`(읽는 곳 0) | Low·P3 | 지우거나 잇는다 |
|
||||
| 1101/06-05 | 남음 | **남음** | `src/adapters/service-worker/service-worker-static-assets.ts:280` | 릴리스마다 전체를 `no-store`로 다시 받는다. Low·P3 | 같은 hash는 이전 캐시에서 복사 |
|
||||
| 1101 R1 | 남음 | **남음** | `src/adapters/service-worker/service-worker-lifecycle.ts:169` | Low·P3 | 쓰거나 지운다 |
|
||||
| 1101 R2 | 남음 | **남음** | `src/adapters/web-push/inbound/push-event-adapter.ts:196`, `notification-click-adapter.ts:356` | Low·P3 | 한 그룹 안 공용 모듈 |
|
||||
| 1101 R3 | 남음 | **남음** | `src/adapters/service-worker/service-worker-entry.ts:170` | Low·P3 | `SERVICE_WORKER_PROTOCOL_VERSION` |
|
||||
| 0929/08-01 | 남음 | **남음** | `src/presentation/i18n/message-contract.ts:8-13`, `src/presentation/layouts/app-shell.tsx:85-86` | **Medium·P1**(1101 README 2.2절 등급 유지). 확장 지점 결정 (가)가 1101 14.1에서 났다 | 제품 locale 선언 파일, `DEV_LOCALES` |
|
||||
| 0929/08-08 | 남음 | **남음** | `src/presentation/providers/session-provider.tsx:88`, `:99`, `src/application/ports/auth-session-port.ts:38` | 참조 기능 쪽 호출(`use-reference-failure-action.ts`)은 지워짐. Low·P3 | `useHref` 문서 경로, 포트 주석 |
|
||||
| 0925 FOLLOW-UP 09-07 | 일부 | **일부** [w2-fe-2 파일] | `scripts/test-sample-removal.ts:469-490`(브라우저 시험 없음), `scripts/lib/removable-template-features.ts`(목록 비어 SKIP) | 예제 기능 제거 드릴 부분은 샘플이 지워져 해당 없음. 제품 기능 제거 드릴이 e2e를 돌지 않는 것은 남는다. Low·P3 | 드릴이 지운 기능을 참조하는 spec을 FE-GATE-008 범위로 돌리거나, 이유를 결정으로 남긴다 |
|
||||
| 0925 FOLLOW-UP 09-08 | 남음(허용한 대안) | **고쳐짐(허용한 대안)** | `tests/fixtures/indexeddb-consumer/domain/local-draft.ts:2-11` | 샘플이 시험 fixture로 옮겨졌고 주석이 남았다(리뷰가 허용한 대안) | — |
|
||||
| 1106/03-01 | 고침 | **고쳐짐(남은 것 남음)** | `application-query.ts:623-646`, `:710-714`, `:765`, `use-app-form.ts:410-449`, `:521-529`, `src/contracts/errors.ts:273-279`. 시험 `form-foundation.test.tsx:1155`, `:1222`, `tests/component/application-mutation-admission.test.tsx:745-790` | 남은 것 ① FR-03: 다시 마운트한 폼의 재전송이 화면 값을 제출 값으로 쓴다(`use-app-form.ts:425`). Medium·P2. ② 폼 밖 `submit`의 같은 입력이 `NOT_APPLIED`면 훅은 키를 지키는데 폼은 retry-later를 보인다. Low·P3 | ① 재전송 결과의 입력을 코디네이터 head에서 받는다. ② 폼이 훅 상태를 읽는다 |
|
||||
| 1106/01-01 | 일부 · 백엔드로 넘김 | **일부 · 백엔드로 넘김** | `fileserver-upload.ts:685-694`, `backend-envelope.ts:96-126`, 시험 `tests/integration/fileserver-upload.test.ts:238`. 백엔드 main `UploadedFileResponse.java:11-18`(이유 칸 없음) | 프론트 몫 성립. 거절 이유는 백엔드 | — |
|
||||
| 1106/02-01 | 고침 | **고쳐짐** | `public-response-cache-adapter.ts:722-728`, 포트 `cache-storage-ports.ts:99-116`, 시험 `tests/unit/public-response-cache-repair.test.ts:1013-1042`, 운영 문서 `client-cache-and-storage-recovery.md:29-34` | marker 쪽은 1105/02-02 | — |
|
||||
| 1106/03-02 | 고침 | **고쳐짐** | 계약 문서(`8156d85f`), 시험 `tests/integration/http-execution-v3-envelope.test.ts`(+58) | — | — |
|
||||
| 1106/03-03 | 고침 | **고쳐짐** | `application-query.ts:290-298`, `:383`, `:586-588`, `:660-661` | 템플릿에 IDEMPOTENT 소비자가 없는 것은 확장 지점 | — |
|
||||
| 1106/04-01 | 고침 | **고쳐짐** | `src/adapters/realtime/reconnect-coordinator.ts`(타입 주석) | 설계 13.1은 이제 기록 문서다. 살아 있는 규칙은 타입 주석이다 | — |
|
||||
| 1106/04-02 | 고침 | **고쳐짐** | `bounded-poll-coordinator.ts:112-130` | 대응표 강제 수단 없음(원래 범위 밖) | — |
|
||||
| 1106/05-01 | 고침 | **고쳐짐** | `docs/design/2026-07-28-client-cache-and-storage-design.md:60`, `docs/adr/VD-13-client-cache-scope-and-persistence.md:75`, `:407`, `:897` | 두 문서가 기록 문서가 되어 검사가 필요 없다 | — |
|
||||
| 1106/06-01 | 고침 | **고쳐짐 · 실행 환경 대기** | `scripts/lib/hosting-probe.ts:129-133`, `:165-175` | 실제 redirect 호스트 등록 미검증 | — |
|
||||
| 1106/06-02 | 고침 | **고쳐짐** | `tests/unit/service-worker-runtime.test.ts`(`1f4b929f`) | 상한을 줄이는 변경 미검출(수정 전에도 같음) | — |
|
||||
| 1106/07-01 | 고침 | **고쳐짐** | 계약 `backend-api-and-server-state-contract.md:192-198` | bulk는 지원 범위 밖 | — |
|
||||
| 1106/07-02 | 고침 | **고쳐짐** | `tests/unit/schema-metadata-policy.test.ts:88-124`, `:170-196`, 생성기 `scripts/create-feature.ts:723-741`, `create-feature-write-slice.ts:212-221` | 템플릿 상태는 `slots`가 0개라 FE-GATE-020(생성 기능 설치)에서만 대상이 있다(`:170-171` 주석). 원래 완료 기준의 "참조 응답 행"은 사라졌다. FE-GATE-020 결과 미확인 | — |
|
||||
| 1106/08-01 | 고침 | **일부(보호 시험 사라짐)** | 코드 `use-app-form.ts:234-249`. 시험이었던 `tests/features/reference-feature/reference-page.test.tsx:817-881`이 `e3c8db48`에서 지워졌고 옮기지 않았다(`git grep '08-01\|remount' -- tests/component` 해당 0) | PA-01. 공용 facade 분기를 지키는 시험이 0개다. 참조 폼의 (B) 안내는 폼이 지워져 해당 없음. Low·P3 | 다시 마운트한 폼 시험 셋을 `tests/component/form-foundation.test.tsx`로 옮긴다 |
|
||||
| 1106/08-02 | 고침 | **고쳐짐** | `scripts/create-feature-write-slice.ts:947`(생성 시험), `tests/unit/create-feature.test.ts` | 이미 생성한 기능은 반영 안 됨(다운스트림 몫) | — |
|
||||
| 1106/08-03 | 고침 | **고쳐짐 · 실행 환경 대기** | `src/presentation/styles/theme/primitives.css:421-435`, `base.css:11`, `src/presentation/design-system/tokens/component.css:10-20`, `tests/visual/scrollbar-gutter.visual.spec.ts` | Firefox·WebKit 미확인. `:has()` 미지원 띠는 디자인으로 받아들였다(기록 `docs/design/2026-07-26-design-system-platform-design.md:552-565`) | — |
|
||||
| 1106/09-01 | 고침 | **고쳐짐** | `docs/manual/01-add-a-feature.md:541-542`, `tests/helpers/mutation-operation-id.ts:11` | descriptor 없는 ID 오타 미검출(문서에 적힘) | — |
|
||||
|
||||
## 3. 남음·일부 행별 상세 (고칠 대상)
|
||||
|
||||
공통: 성격·관점·통제·증거를 칸으로 적는다. 증거는 읽기만 했으면 E1이다. 결정 대기(색인 없음) 7행은 3.3절에 모았다.
|
||||
|
||||
### 3.1 새로 본 것
|
||||
|
||||
**PA-01 — 정리 2단계가 1106/08-01·DR-03·FR-01의 다시 마운트한 폼 시험을 옮기지 않고 지웠다**
|
||||
|
||||
| 칸 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함(검사 범위가 줄었다. 결함 패턴 "수정이 검사 범위를 좁힌다") |
|
||||
| 관점 | 10, 21, 5 |
|
||||
| 등급 | Low·P3. 동작은 그대로다. 템플릿 생성 폼은 확인 뒤 목록으로 가서 그 분기의 화면 결과가 안 보인다. 공용 facade를 직접 쓰는 다운스트림에서만 닿는다 |
|
||||
| 통제·증거 | M0(이 분기를 보는 시험 없음) · E1 |
|
||||
| 근거 | 지운 시험: `e3c8db48^:tests/features/reference-feature/reference-page.test.tsx`의 `:670`(1105/08-04 저장 중 떠났다 돌아옴), `:776`(FR-01 422 mismatch), `:817`(08-01 확인 뒤 포커스), `:839`(DR-03 입력 보존), `:867`(08-01 (B)). 이 커밋 본문은 "샘플이 맡던 시험 대상은 앞 커밋들이 옮겼다"고 적지만, `git log bbde570..HEAD -- tests/component/form-foundation.test.tsx`에는 옮긴 커밋이 없다. 남은 코드 `src/presentation/forms/use-app-form.ts:234-249`(`settleApplied`의 다시 마운트 분기)와 `:425`(`?? values`) |
|
||||
| 발생 조건 | 누군가 그 분기를 지우거나 바꾼다 |
|
||||
| 영향 | 다시 마운트한 폼에서 확인을 누르면 결과 표시·포커스가 사라진다(1106/08-01 이전으로 돌아감). 또는 보내지 않은 입력을 저장됨으로 지운다(DR-03 이전). 어떤 게이트도 실패하지 않는다 |
|
||||
| 최소 개선 | `form-foundation.test.tsx`의 `CoordinatedForm` harness로 "저장 중 unmount → 다시 mount → 결과 불명 → 확인" 시험 셋을 옮긴다(포커스, 입력 보존, 422 mismatch 유지) |
|
||||
| 완료 기준 | 실험 PA-X1의 변이에서 새 시험이 실패한다 |
|
||||
| RED | 실험 PA-X1. 지금은 변이를 넣어도 `test:component`가 통과할 것이다(예측). 시험을 옮긴 뒤에는 같은 변이에서 실패해야 한다 |
|
||||
|
||||
**PA-02 — 결정 대기 7행이 결정 색인에 없다**
|
||||
|
||||
| 칸 | 내용 |
|
||||
|---|---|
|
||||
| 성격 | 확인된 결함(문서. repo가 정한 결정 대기 형식을 안 채움) |
|
||||
| 관점 | 26, 9, 5 |
|
||||
| 등급 | Low·P3 |
|
||||
| 근거 | 색인 3.1절(`docs/work/reference/decisions.md:77-87`)에는 D1·D2·D3·D11·D6(1105)뿐이다. 같은 문서 3절은 "이 형식을 채우지 못하면 결정 대기가 아니라 미완이다"라고 적는다. 빠진 행은 1105/06-02, 1103/03-01 (2), 0929/02-02, 1101/02-02, 0929/02-06, 0929/04-02, 0929/04-03이다. 출처는 1105 README 16.6 「결정 대기」와 1106 영역 문서이고, 선택지·결정할 사람·재검토 조건이 없다 |
|
||||
| 최소 개선 | 7행을 3절 형식(왜 못 고치나·선택지·결정할 사람·결정 전까지·재검토 조건)으로 3.1절에 올린다. 아니면 고칠 대상으로 바꾼다 |
|
||||
| 완료 기준 | 「결정 대기」 표시가 붙은 모든 지난 발견이 3.1절에 한 행씩 있다 |
|
||||
| RED | `scripts/check-work-docs.py`나 문서 시험에 "리뷰 README의 결정 대기 ID ⊂ decisions.md 3.1" 대조를 더할 수 있다. 다만 리뷰 문서를 시험이 읽으면 `.claude/rules/tests.md` 8을 어긴다. 그래서 사람이 하는 단계로 둔다 |
|
||||
|
||||
### 3.2 이월 고칠 대상 (결정 대기 아님)
|
||||
|
||||
모두 성격은 표에 적은 것이다. 증거는 E1이다(코드가 `bbde570` 뒤 0줄 바뀐 행은 1106 실험 결과를 다시 쓰지 않았다).
|
||||
|
||||
| ID | 성격·관점 | 등급 | 통제 | 발생 조건 → 영향 | 최소 개선 | 완료 기준 | RED 시험 아이디어 |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| 1105/01-02(프론트 몫) | 구조적 위험 · 17, 21, 23 | Low·P3 | M2(사람이 읽은 표) | 백엔드 pin을 올릴 때 Fileserver code가 바뀐다 → client가 결과 불명을 `NOT_APPLIED`로 잘못 읽는다 | pin `backend.scaffoldSources`처럼 Fileserver 출처 행(`FileserverErrorCode.java`, "게시 전 5xx 넷", copiedTo `fileserver-upload.ts` `NOT_APPLIED_5XX_CODES`)을 더하고 readers에 그 파일을 넣는다 | `check:backend-contract-drift`가 Fileserver 행을 대조한다 | 변이: pin 사본의 code 하나를 바꾸면 `tests/unit/backend-contract-pin.test.ts`가 실패한다(새 행 기준) |
|
||||
| 1105/02-02 | 확인된 결함 · 6, 11, 28, 17 | Low·P3 | M2 | 후보·rollback 대상의 marker 본문이 계속 읽히지 않는다 → rollback 불가, 활성 release 조회 전부 실패 | `public-response-cache-adapter.ts:463-468`에서 `CORRUPT_DATA` 밖의 marker 실패도 다시 받아 덮어쓴다(지우지 않음). 포트 주석 `:69-71`의 "or lookup"을 뺀다. 운영 문서에 marker 절차 한 줄 | 02-R1 X1·X2 순서에서 같은 manifest stage 뒤 activate가 성공한다 | `public-response-cache-repair.test.ts`에 "marker body stays NotReadable → stage same manifest → activate ok". 지금은 `UNAVAILABLE/RETRY`로 실패한다 |
|
||||
| 1103/03-01 (3) | 확인된 결함(코드와 결정 기록 어긋남) · 9, 17 | Low·P3 | M1 | 문서를 읽고 409를 conflict로 기대한 사람 → 다른 화면 | VD-04 맨 아래에 날짜 붙은 「보완」 절: "기능이 `refusalMessages`로 선언한 쓰기 전 거절(409 포함)은 필드 오류로 보인다. 결정 5는 선언 안 된 409 conflict에만 적용된다" | VD-04 본문과 코드가 같은 말을 한다 | 문서만. `verify:documentation` |
|
||||
| 1103/09-05 | 확인된 결함 · 3, 25, 28 | Medium·P2 | M2 | SW `ACTIVE`를 켠 제품 → 활성화 화면을 붙이려면 템플릿 파일을 고친다 | `ProductServiceWorkerWiring`에 `onUpdateWaiting?(activate)`·`onReloadRequired?()` 칸을 열고 템플릿 조립이 controller에 잇는다 | 제품 소유 파일만 고쳐 활성화 안내가 뜬다. 템플릿 파일 diff 0 | `tests/component/runtime-composition-service-worker-product-wiring.test.ts`에 "onUpdateWaiting 칸이 호출된다". 지금은 칸이 없어 타입 단계에서 실패한다 |
|
||||
| 0929/05-01 ③ | 확인된 결함(결정 1101 14.1과 어긋남) · 6, 11, 28 | Low·P3(purge 영향 밖으로 낮춤) | M1 | 손상 chunk reference 행 하나 → reconcile·GC가 영구히 멈춘다(바이트 누수) | `isChunkReferenced`가 손상 행을 "참조됨"으로 돌려주고 수를 센다 | 손상 행 하나가 있어도 reconcile이 ok와 손상 수를 돌려준다 | OPFS 메모리 fake에 손상 reference 행 → reconcile. 지금은 `CORRUPT_DATA`다 |
|
||||
| 1101/05-06 | 미검증 · 10 | Low·P3 | M0 | 분기를 지우는 변경 → 아무 시험도 실패하지 않는다 | codec·adapter 직접 시험 셋(TTL 모양, `__proto__` 키, accessor) | 변이 W2·W5·W6이 실패한다 | 새 시험. 변이로 확인 |
|
||||
| 1101/01-03 | 구조적 위험 · 14, 5, 19 | Low·P3 | M2 | 동시성을 올리며 copyFactor를 1로 낮춘다 → 모바일 메모리 부족 | `PART_BUFFER_COPIES = 4` 하한과 복사 위치 주석 | `partBufferCopyFactor: 1` 정책이 조립 때 거절된다 | `resolveResumableUploadRuntimePolicy({ partBufferCopyFactor: 1 })` 거절 시험. 지금은 통과한다 |
|
||||
| 0929/01-03 | 구조적 위험 · 19, 23, 9 | Low·P3 | M1 | 느린 업링크를 지원하려고 정책만 낮춘다 → PUT이 실행기 deadline에서 끊긴다 | `runtime-policy.ts:26-31` 주석과 `docs/architecture/optional-adapter-recipes.md`에 두 값을 함께 낮추라고 적는다. 또는 조립이 정책 값을 실행기에 넘긴다 | 0929 실험 X3에서 정책만 낮춰도 PUT 1회에 성공하거나, 살아 있는 문서가 두 곳을 적는다 | X3을 단위 시험으로(fake timer, PUT 7초) |
|
||||
| 0929/01-04 | 구조적 위험 · 21, 27, 8 | Low·P3 | M2 | file-transfer 어댑터만 지운다 → 게이트가 원인 없이 실패 | 없는 필수 소비자는 건너뛰고, `release-artifacts.ts:1182`가 레시피 ID를 말한다 | 어댑터만 지운 fixture에서 원인을 말하는 메시지로 실패하거나 통과한다 | fixture 시험 |
|
||||
| 0929/01-05 | 확인된 결함(계약 빈칸) · 17, 8, 23 | Low·P3 | M1 | `abort()` 실패 → 호출자가 무엇을 할지 모른다 | 포트 주석에 `abort()` 표. 닫힌 runtime의 `RESUME`을 `NONE`으로 | 모든 `abort()` 실패 recovery가 표의 행동 하나다 | 닫힌 runtime `abort()`의 recovery가 `NONE`인지. 지금은 `RESUME`이다 |
|
||||
| 0929/02-03 | 확인된 결함(문서) · 9 | Low·P3 | M0 | 다운스트림이 영향 경로를 찾는다 → 없는 경로 | `CHANGELOG.md:624` 경로와 레시피 이름 | 행이 `src/adapters/browser-files/`와 service-worker-pwa를 가리킨다 | 문서만 |
|
||||
| 1101/03-04 | 구조적 위험 · 23, 6, 5 | Low·P3 | M1 | 기능의 `mapProblem`이 `VALIDATION_REJECTED`를, 분류기가 `MAYBE_APPLIED`를 준다 → 필드 오류와 결과 불명 화면이 함께 뜬다 | 폼이 `MAYBE_APPLIED`를 먼저 본다(reauth 뒤). 아니면 그 조합을 진단 1건으로 남긴다 | E8 순서에서 화면 안내가 하나다 | `form-foundation.test.tsx:1131` 시나리오에 "결과 불명 화면만 있다" 단언. 지금은 필드 오류도 있다 |
|
||||
| 0929/03-02 | 확인된 결함(운영 문서 빈칸) · 7, 18, 8 | Low·P3(조정) | M1 | 교차 origin에서 백엔드가 헤더 목록을 좁힌다 → 모든 요청이 `NETWORK_FAILURE` | FE-RB-003 첫 분류에 CORS·preflight. 배포 절차에 `curl -X OPTIONS … -H 'Access-Control-Request-Headers: …x-correlation-id'` | 0929 완료 기준 셋 | 문서만 |
|
||||
| 0929/05-05 | 확인된 결함 · 11, 28 | Low·P3 | M1 | 롤백 중(N-1 탭) 계정 삭제 → `INCOMPATIBLE`로 DB를 못 지운다 | 승인된 ACCOUNT_DELETION은 `INCOMPATIBLE`에서도 전체 삭제를 쓴다 | 미래 버전 DB에서 계정 삭제가 DB를 지운다 | fake-indexeddb `VersionError` 시험 |
|
||||
| 0929/05-06 | 확인된 결함(두 계약 갈림) · 23 | Low·P3 | M0 | 129~512자 proof → IndexedDB만 거절 | `src/adapters/platform/` 상수 하나 | 두 런타임이 같은 정규식을 import한다 | 129자 proof 표 시험 |
|
||||
| 0929/05-07 | 구조적 위험 · 9, 23 | Low·P3 | M0 | 한 사본만 고친다 → digest가 갈린다 | `src/adapters/platform/canonical-json.ts`와 `sameScope` 하나 | 사본 0 | 정적(`git grep`) |
|
||||
| 0929/05-10 | 개선 제안 · 19, 25 | Low·P3 | — | 한 origin에 앱 둘 → journal DB 충돌 | 접두사를 조립 옵션으로(기본값 유지) | 옵션으로 이름이 바뀐다 | 단위 시험 |
|
||||
| 0925/06-05 | 확인된 결함(관측 빈칸) · 7, 8 | Low·P3 | M1 | 업데이트 워커 `redundant`, `update()` 실패 → 아무 기록 없음 | observe 이벤트 `update_install`·`update_check`와 outcome | 두 실패가 observe에 남는다 | page controller 시험: `redundant` 상태 전이 → observe 기록. 지금은 0건 |
|
||||
| 0925/06-08 | 구조적 위험 · 19, 18, 21 | Low·P3 | M0 | 제품이 `build.assetsDir`를 바꾼다 → 사전 캐시·fallback·probe가 조용히 빈다 | `vite.config.ts`가 `BUILD_ASSET_DIRECTORY`에서 `assetsDir`를 정한다. decoder가 빈 manifest를 거절한다 | 두 값이 한 곳에서 나온다 | `tests/unit/vite-build-inputs.test.ts`에 대조 |
|
||||
| 0925 P3 | 개선 제안 · 10 | Low·P3 | — | spec 유지비 | 도우미 옵션 | spec에서 덧붙이기 코드가 빠진다 | — |
|
||||
| 1101/06-03 | 구조적 위험(흔적) · 9, 24 | Low·P3 | — | 읽는 사람이 쓰이는 프로토콜로 오해한다 | 두 kind와 guard 상수를 지우거나 잇는다 | 읽는 곳 없는 정의 0 | 정적 |
|
||||
| 1101/06-05 | 개선 제안 · 14 | Low·P3 | — | 릴리스마다 전체를 다시 받는다 | 같은 hash는 이전 캐시에서 복사 | 바뀐 자산만 fetch | fetch 수 시험 |
|
||||
| 1101 R1 | 흔적 · 9 | Low·P3 | — | — | `void` 줄을 지우거나 쓴다 | — | 정적 |
|
||||
| 1101 R2 | 구조적 위험(사본) · 23 | Low·P3 | M0 | 한 벌만 고친다 | `web-push` 그룹 안 공용 함수 | 한 벌 | 정적 |
|
||||
| 1101 R3 | 일관성 · 23 | Low·P3 | — | 버전을 올릴 때 하나가 빠진다 | 상수 사용 | 리터럴 0 | 정적 |
|
||||
| 0929/08-01 | 확인된 결함 · 3, 19, 25 | Medium·P1 | M1 | 한 언어 제품 → 가짜 번역을 만들거나 템플릿 파일을 고친다. 운영 셸에 Pseudo·RTL이 보인다 | locale 선언 파일(`PRODUCT_LOCALES`, `DEV_LOCALES`)에서 다섯 곳을 파생 | ko-KR만 선언한 fixture에서 `check:types`·`check:i18n` 통과. 운영 셸에 Pseudo·RTL 없음 | 그 fixture로 `tests/unit` 시험. 지금은 en-US catalog가 없으면 타입 오류다 |
|
||||
| 0929/08-08 | 확인된 결함(계약 빈칸) · 17, 18, 15 | Low·P3 | M1 | base path 배포 → 로그인 뒤 앱 밖으로 돌아간다 | `useHref`로 문서 경로를 넘기고 포트 주석에 기준(같은 origin, basename 포함)을 적는다 | 0929 E11에서 `beginSignIn("/app/fixture/items?x=1#results")` | `session-provider` 시험에 basename `/app` |
|
||||
| 0925 FU 09-07 [w2-fe-2 파일] | 미검증 · 27, 10 | Low·P3 | M1 | 제품 기능 제거 → spec이 남아 e2e에서만 깨진다(본문 ID 잔여 검사는 `-` 든 이름만) | 드릴이 지운 기능을 이름으로 가리키는 spec 목록을 내거나, 이유를 결정으로 남긴다 | 드릴 보고서에 브라우저 단계 결과나 결정 출처가 있다 | — |
|
||||
| 1106/03-01 ① FR-03 | 확인된 결함 · 6, 12, 24 | Medium·P2 | M0(시험 없음) | 저장 중 떠났다 돌아온 폼에서 다른 값을 입력한 채 "같은 요청으로 다시 보내기" → 실제로는 원래 입력이 가고, 폼은 화면 값을 제출 값으로 둔다. 입력이 지워지거나 이탈 확인이 꺼질 수 있다 | `resendUnknown`이 결과를 코디네이터 head의 입력 기준으로 정리한다. 다시 마운트한 폼에서는 화면 값을 건드리지 않는다 | 다시 마운트 → 다른 값 입력 → 재전송 성공 뒤 화면 값과 dirty가 남는다 | PA-01과 같은 harness. 지금은 입력이 원래 제출 값으로 바뀌거나 지워진다(예측) |
|
||||
| 1106/03-01 ② | 확인된 결함(작음) · 23, 24 | Low·P3 | M1 | 폼 밖에서 같은 입력으로 `submit` → `NOT_APPLIED` → 폼은 retry-later, 훅은 결과 불명 | 폼이 `canResendUnknownEffect`·결과 불명 상태를 읽어 같은 화면을 보인다 | 두 상태가 같다 | component 시험 |
|
||||
| 1106/08-01 | → PA-01 | Low·P3 | M0 | 위 | 위 | 위 | 위 |
|
||||
|
||||
### 3.3 결정 대기(색인 없음) — 고치지 않는 이유
|
||||
|
||||
이 행들은 소유자 선택이 필요해서 고치지 않는다. 다만 색인에 없어 「미완」이다(PA-02).
|
||||
|
||||
| ID | 왜 못 고치나 | 선택지(앞이 권고) | 결정할 사람 |
|
||||
|---|---|---|---|
|
||||
| 1105/06-02 | 워커 없는 빌드에서 자산 probe를 돌릴지가 정책이다 | (가) 워커 없을 때 redirect 행을 빼고 `nosniff` 행만 둔다 (나) 그대로 두고 이유 문구를 워커 중립으로 바꾼다 | 프론트 소유자 |
|
||||
| 1103/03-01 (2) | `IDEMPOTENCY_RECOVERY_REQUIRED` 뒤 재전송 버튼을 거둘지가 백엔드 §2 문장과 맞물린다 | (가) 그 답이면 `resendable=false` (나) 그대로 두고 화면 안내만 | 프론트 템플릿 담당 |
|
||||
| 0929/02-02 | `inspect()` 시그니처 변경(BREAKING) | (가) `signal?`과 `verified: "UNKNOWN"` 셋째 값 (나) 문서만 | 프론트 소유자 |
|
||||
| 1101/02-02 | 허용 짝 표의 범위 | (가) media type별 허용 확장자 표 (나) 제품 검토로 둔다 | 프론트 소유자 |
|
||||
| 0929/02-06 | 루트 `AGENTS.md` 꼭 지킬 것 2가 이 예외를 kernel로 적는다 | (가) 타입 둘을 `src/contracts/`로 옮기고 예외를 지운다(0929 실험에서 게이트 통과) (나) 유지 | 템플릿 소유자 |
|
||||
| 0929/04-02 | SSE EOF 분류와 bridge 설계 | 0929 영역 문서의 선택지 | 프론트 소유자 |
|
||||
| 0929/04-03 | 설계 5.3·6.3 중 어느 규칙인가 | (가) 코드대로(상한 밖은 버림)를 살아 있는 문서에 적는다 (나) 상한 밖이면 종료 | 프론트 소유자 |
|
||||
|
||||
### 3.4 고칠 대상 목록 (결정 대기 아님, 31건 + 정리 1건)
|
||||
|
||||
1. PA-01 / 1106/08-01 — 다시 마운트한 폼 시험 복원(Low·P3)
|
||||
2. 1106/03-01 ① FR-03 — 다시 마운트한 폼 재전송이 화면 값을 제출 값으로 씀(Medium·P2)
|
||||
3. 1106/03-01 ② — 폼 밖 `submit` 재저장의 retry-later 불일치(Low·P3)
|
||||
4. 1103/09-05 — SW 활성화 화면의 제품 자리(Medium·P2)
|
||||
5. 0929/08-01 — 제품 locale 선언 자리(Medium·P1)
|
||||
6. 1105/01-02 프론트 몫 — Fileserver code 표 pin 대조(Low·P3)
|
||||
7. 1105/02-02 — 읽히지 않는 release marker 다시 쓰기 + 포트 주석(Low·P3)
|
||||
8. 1103/03-01 (3) — VD-04 보완 절(Low·P3)
|
||||
9. 0929/05-01 ③ — 손상 chunk reference가 reconcile·GC를 멈춤(Low·P3)
|
||||
10. 1101/05-06 — Web Storage W2·W5·W6 시험(Low·P3)
|
||||
11. 1101/01-03 — copyFactor 하한 상수(Low·P3)
|
||||
12. 0929/01-03 — 업링크 기본값 세 곳, 살아 있는 안내 없음(Low·P3)
|
||||
13. 0929/01-04 — adapter-inventory 파일 이름 고정, 원인 없는 ZodError(Low·P3)
|
||||
14. 0929/01-05 — `abort()` recovery 표(Low·P3)
|
||||
15. 0929/02-03 — CHANGELOG 0.2.0 경로(Low·P3)
|
||||
16. 1101/03-04 — 필드 오류와 결과 불명 동시 표시(Low·P3)
|
||||
17. 0929/03-02 — CORS runbook·preflight 점검(Low·P3, 조정)
|
||||
18. 0929/05-05 — 롤백 중 계정 삭제 전체 삭제(Low·P3)
|
||||
19. 0929/05-06 — proof 정규식 통일(Low·P3)
|
||||
20. 0929/05-07 — canonical JSON·`sameScope` 사본(Low·P3)
|
||||
21. 0929/05-10 — journal DB 접두사 옵션(Low·P3)
|
||||
22. 0925/06-05 — 업데이트 실패 관측(Low·P3)
|
||||
23. 0925/06-08 — `assetsDir` 상수와 Vite 설정 연결(Low·P3)
|
||||
24. 0925 P3 — SW update spec 도우미 옵션(Low·P3)
|
||||
25. 1101/06-03 — 쓰이지 않는 프로토콜 kind·guard 상수(Low·P3)
|
||||
26. 1101/06-05 — 사전 캐시 재사용(Low·P3)
|
||||
27. 1101 R1 — `void` 참조(Low·P3)
|
||||
28. 1101 R2 — `validateActiveFence` 두 벌(Low·P3)
|
||||
29. 1101 R3 — 프로토콜 버전 리터럴(Low·P3)
|
||||
30. 0929/08-08 — 로그인 복귀 주소 기준(Low·P3)
|
||||
31. 0925 FU 09-07 [w2-fe-2 파일] — 제거 드릴의 브라우저 단계(Low·P3)
|
||||
32. (정리) PA-02 — 결정 대기 7행을 색인 3.1절에 올림(Low·P3)
|
||||
|
||||
## 4. 넘길 것
|
||||
|
||||
- → 시험 렌즈(`fe-testing`): `e3c8db48`이 지운 참조 기능 시험 1,044줄 가운데 이 범위 밖의 것이 있다. 아래 시험의 대응 시험이 남았는지 봐야 한다. PA-01과 같은 원인이고, 01~09 영역 밖 행이라 여기서 판정하지 않았다.
|
||||
- `:670`(1105/08-04 저장 중 떠났다 돌아온 폼)
|
||||
- `:883-928`(0929/08-04 요청 id 표시)
|
||||
- `:252-278`(인증 실패 뒤 로그인 시작·실패 대체 경로)
|
||||
- → 백엔드 총괄(넘김 그대로, 백엔드 main `a7e38c10`에서도 안 풀림):
|
||||
- Fileserver 202 state 목록(`docs/fileserver/http-contract.md:9`)
|
||||
- 504 ambiguous 표시, `Idempotency-Key`
|
||||
- REJECT 이유 칸(`UploadedFileResponse.java`)
|
||||
- realm public client
|
||||
- `RateLimitInterceptor` 비동기 재디스패치
|
||||
- → 총괄: FE-GATE-020 결과로 07-02가 생성 기능 상태에서 실제로 검사되는지 확인한다(템플릿 상태 `slots` 0).
|
||||
|
||||
## 5. 실험 요청
|
||||
|
||||
**PA-X1 — 다시 마운트 분기에 시험이 없음을 보인다(PA-01 RED)**
|
||||
|
||||
- 명령: `scripts/verify.sh exec -- node scripts/run-vitest.ts run tests/component --reporter=default`
|
||||
- env: 기본(CI 불필요). 시간 상한 10분.
|
||||
- 기대: 변이 뒤에도 모두 통과한다. 그러면 PA-01이 E3으로 확정된다. 실패하는 시험이 있으면 PA-01은 틀린 발견이다.
|
||||
- 변이 패치:
|
||||
|
||||
```diff
|
||||
--- a/src/presentation/forms/use-app-form.ts
|
||||
+++ b/src/presentation/forms/use-app-form.ts
|
||||
@@ -239,10 +239,6 @@
|
||||
// confirm button, goes to the feedback area that shows it. The values
|
||||
// on screen were never sent, so they and the dirty state stay as they
|
||||
// are (diff review of 1106/08-01).
|
||||
- focusFeedbackRef.current = focusIsLost();
|
||||
- setFieldErrors({} as FieldErrors<Values>);
|
||||
- setFormErrors([]);
|
||||
- setResult("success");
|
||||
return;
|
||||
}
|
||||
settleSuccessfulValues(submittedValues);
|
||||
```
|
||||
|
||||
## 6. 결함 아님으로 판정한 의심
|
||||
|
||||
- 1103/03-02 bulk `results` 미지원: 지원 범위 밖으로 적혀 있다(`review-criteria.md:43`, 계약 `:192-198`).
|
||||
- 1106/03-03 IDEMPOTENT 소비자 0: 소비자 없는 확장 지점이다.
|
||||
- 1106/07-02 템플릿 상태에서 `slots` 0개: 생성 기능을 넣는 FE-GATE-020이 같은 시험을 돈다. 생성기가 두 칸을 쓴다(`scripts/create-feature.ts:723-741`).
|
||||
- 1106/04-01·05-01·08-03의 규칙·근거가 기록 문서(`docs/design/`, `docs/adr/`)로 옮겨진 것: 살아 있는 근거가 코드 주석에 있다. 기록 문서는 고치지 않는 것이 규칙이다.
|
||||
- 1103/03-01 (1) 거짓 "저장했습니다.": 템플릿이 그리는 경로(생성 폼)는 확인 뒤 목록으로 가서 실제 상태를 보인다. 확인 버튼 하나만 두는 것은 VD-04 결정 9다. 공용 facade를 직접 쓰는 경우는 Medium·P2 모양이지만, 같은 길이 1103/03-01 (2)·결정 대기와 묶여 있어 따로 세지 않았다.
|
||||
- 1105/01-02 커밋 `471b001` 본문의 백엔드 방법 (b): 올린 이력이라 고치지 않는다(1106 README 16.2절 14-02와 같은 규칙). repo 안 문구는 목표로 맞게 적혀 있다.
|
||||
- 0929/02-06을 「새 파일 단위 예외」로 보는 것: 기존 kernel 셋 안의 예외라 새 예외 금지와 무관하다.
|
||||
@@ -0,0 +1,533 @@
|
||||
# round9 PB — 지난 발견 재판정 (대상 `5250ff95`, 트리 `75cc3752`)
|
||||
|
||||
> round9 리뷰(2026-11-12, 대상 main `5250ff95`)의 영역 기록이다. 서브에이전트가 쓴 원문을 그대로 옮겼다. 바꾼 것은 이 인용 블록과, 작업 폴더 절대 경로를 `(작업 폴더)`로 줄인 것뿐이다. 발견 ID는 이 파일의 이름표(R-01 등)이고, 라운드 ID(`1112/NN-MM`)와의 대응은 [README](2026-11-round9-review.md) 15절이다.
|
||||
|
||||
|
||||
리뷰어 PB. 코드를 고치지 않았다. 노트북에서는 `git`·`grep`·`sed`·`python3 -I`(파일 읽기)만 썼다. desktop에서는 읽기만 했다(`/tmp/claude-gates/r9fe-base/summary.txt`, 진행 중인 verify worktree `/tmp/verify-1794485218-768855.hGvCTt`의 `artifacts/` 파일 읽기). 그 worktree의 트리는 `5250ff95`와 같은 `75cc3752`다.
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- 60행(13.4절 51행 + 16.4절 1106 새 발견 9행. 1103/15-02는 두 목록에 다 있어 한 행)을 다시 판정했다.
|
||||
- **고쳐짐 15 · 일부 18 · 남음 23 · 재발 2 · 해당 없음 2 · 틀린 발견 0.**
|
||||
- 붙인 표시: 결정 대기 11, runner로 확인 필요 5, 실행 환경 대기 1(namespace 허용 호스트의 worktree), 결정 재검토 1(D9).
|
||||
- **재발 2건.**
|
||||
- 1105/15-04: 2026-11-07 예제 화면을 지운 뒤 템플릿에는 공개 기능 라우트가 없다. lab이 기능 라우트를 하나도 재지 않는다. 생성 라우트는 모두 `session-required`라 lab 대상이 될 수 없다.
|
||||
- 1106/14-02: 그 뒤 통합에서 커밋 본문이 다시 짓기 전 해시를 가리킨다. `30a379f`를 커밋 셋이, `8c4b09b7`을 커밋 하나가 가리킨다. 대조 기록도 없다.
|
||||
- **새 사실 하나가 여러 행을 바꿨다.** 참조 기능과 예제 화면을 지웠다(`e3c8db48`, 2026-11-07). 그래서 초기 JS가 194,403 B, 17파일이 됐다(FE-GATE-012, 이번 desktop merge 실행, CI env). 예산 206,848 B는 D9 규칙(드릴 + 1 KiB를 KiB 단위로 올림)보다 약 4 KiB 크다. 규칙의 "다시 볼 때"에 "기준선이 크게 줄 때"가 없어서 아무도 다시 재지 않았다. 그래서 1106/15-01을 일부로 본다(결정 재검토).
|
||||
- **결정 색인 빈틈.** 결정 대기 11건 중 `docs/work/reference/decisions.md` 3.1절에 있는 것은 D1·D6(1105)·D11 셋뿐이다. 나머지 8건은 색인에 없다. 그 문서 3절(`decisions.md:64`)은 "이 형식을 채우지 못하면 결정 대기가 아니라 미완"이라고 적는다. 그래서 이 8건은 repo 자신의 규칙으로는 미완이다(3절 넘길 것 PB-N1).
|
||||
- 고칠 대상(결정 대기가 아닌 남음·일부·재발과 1106/12-02의 남은 것)은 29건이다. 목록은 7절이다.
|
||||
|
||||
## 1. 범위
|
||||
|
||||
- 읽은 것:
|
||||
- brief 둘, `.claude/agents/reviewer.md`, `docs/work/reference/review-criteria.md`(2·3·6·8절), `docs/work/reference/decisions.md`.
|
||||
- 1106 README 13.4·16절, 1106 영역 문서 10~16의 2·3절.
|
||||
- 각 ID의 원래 완료 기준: 1105·1103·1101·0929 영역 문서. ID마다 `awk`로 「최소 개선 방향」「완료 기준」「심각도」를 뽑았다.
|
||||
- 현재 커밋의 코드·설정·문서. 행마다 근거 칸에 적었다.
|
||||
- 렌즈 스킬: 따로 받지 않았다. 판정 기준은 각 ID의 원래 완료 기준과 `review-criteria.md` 6절이다. 코드는 들어왔는데 완료 기준을 실행하지 않았으면 「일부」다.
|
||||
- 옮겨진 파일:
|
||||
- `tests/unit/browser-rpc-remediation.test.ts` → `tests/unit/browser-rpc/browser-rpc-remediation.test.ts`
|
||||
- `config/ci/contract-baseline.json` 삭제(`f6b2b96c`)
|
||||
- `tests/fixtures/hosting/response-headers.json`(CSP fixture 위치)
|
||||
- 목표 설계 문서는 `docs/design/`(기록)로 옮겨졌다.
|
||||
- 이번 desktop 실행에서 읽은 값(CI env, 실제 runner 아님, E3):
|
||||
- FE-GATE-012: `Bundle budget: PASS (initial JS 194403 / 206848 gzip bytes, 17 / 32 files)`
|
||||
- FE-GATE-013: 사전 점검에서 namespace 제한을 이름으로 적고 rc=1
|
||||
- `a11y.json`: `scope` 3개, `notChecked: []`
|
||||
- unit junit: RPC 테스트 셋이 1.03~1.06 s. 파일별 시간 합계는 표의 1101/10-05 행에 있다.
|
||||
- 확인 못 한 것:
|
||||
- FE-GATE-020: 이 리뷰를 쓰는 동안 아직 돌고 있었다. 드릴의 초기 JS 값, 드릴 안 `tests/unit` 실행 횟수, sample-removal SKIP 줄은 못 봤다.
|
||||
- 실제 Gitea runner의 결과. merge job 셋, release 단계는 한 번도 안 돌았다.
|
||||
- FE-GATE-026(lab, release 단계)
|
||||
- 다운스트림 repo. memento·tech-log를 열지 않았다.
|
||||
|
||||
## 2. 재판정 표
|
||||
|
||||
상태: 고쳐짐 / 일부 / 남음 / 재발 / 틀린 발견 / 해당 없음. 근거 줄은 `5250ff95` 기준이다.
|
||||
|
||||
| ID | 11-06 상태 | 지금 상태 | 근거 `file:line` | 남은 것 · 지금 등급 | 고칠 방향 |
|
||||
|---|---|---|---|---|---|
|
||||
| 1105/10-03 | 남음(제안) | 남음(제안) | `package.json`에 변이 도구 없음. `docs/work/reference/defect-patterns.md:34` "변이 도구는 미조치" | 변이 도구 없음 · Low·P3 개선 제안 | 소유자 결정 필요(dev 의존성 추가). 들이지 않을 거면 결정으로 닫는다 |
|
||||
| 1105/12-01 (+1105/11-02) | 일부 · 실행 환경 대기 | 일부 · runner로 확인 필요 | 사전 점검 `scripts/check-system-test-prerequisites.ts:39-43`, `:90-95`. 이번 FE-GATE-013 로그가 제한을 이름으로 적는다(E3). 요구 목록 `docs/operations/ci-quality-gates.md:187-205`, `docs/security/supply-chain.md:187-190`, `docs/testing/taxonomy.md:15`, `:66-68`. 대기 함수 메시지 `tests/system/ci-runner/ci-artifact-contract.test.ts:1783`, `:1813` | ① 허용 호스트에서 PASS 뒤 전부 통과: runner로 확인 필요(D8: 「충족」은 runner로만). ② 파일 대기 시간 초과에 provider stderr가 없다 · Low·P3 | ② 대기 함수가 시간 초과 때 그 실행의 stderr를 메시지에 붙인다 |
|
||||
| 1105/12-03 | 남음 | 고쳐짐 | `CLAUDE.md:1`(`@AGENTS.md`, 게이트 목록 없음). `README.md:203-207`이 merge stage를 `gates.json`에서 읽어 돈다. `AGENTS.md:28` | 없음 | — |
|
||||
| 1105/12-04 | 일부 | 일부 · 결정 대기(D6, `decisions.md:87`) | `README.md:221` "한 checkout에서는 게이트를 하나씩"(M1). `scripts/verify.sh:213`, `:270`은 `flock`으로 줄 세운다 | `ci:gate` 두 실행이 같은 `dist`·`artifacts/`를 쓴다 · Medium·P2 | D6 결정 뒤 |
|
||||
| 1105/13-01 | 일부 · 실행 환경 대기 | 일부 · runner로 확인 필요 | `.gitea/workflows/quality-gates.yml:280-293`(`if: always()`, 7경로) | release 단계 run의 산출물 확인(runner, `stage=release` dispatch) | 코드 수정 없음. runner 확인 |
|
||||
| 1105/14-01 | 고쳐짐 | 해당 없음 | 예제 기능 삭제 `e3c8db48`. `scripts/lib/removable-template-features.ts:26`(빈 목록), `PRODUCT.md:33` | 위험이던 "예제를 지우면 문서 검사 실패"의 대상이 없다. 장치는 남았고 FE-GATE-020이 목록 전체를 돈다(빈 목록은 SKIP, `scripts/test-sample-removal.ts:72-81`) | — |
|
||||
| 1105/15-04 | 일부 · 결정 대기 | **재발** · 결정 대기(두 묶음) | `scripts/lib/lab-performance.ts:55-68`(공개+내비게이션만), `scripts/create-feature.ts:578`, `scripts/create-feature-write-slice.ts:130`(`session-required`), `docs/operations/performance-evidence.md:121-128`("템플릿은 기능이 없어 재지 않는다"), `scripts/test-performance.ts:342-344` | 완료 기준 "`lab.json`에 기능 라우트 시간과 표본"이 템플릿에서 다시 안 선다. 생성 기능도 재지 않는다 · Low·P2 | lab이 생성 기능 라우트를 잰다(3절 상세) |
|
||||
| 1105/16-01 | 고쳐짐 | 고쳐짐 | `docs/manual/03-outside-feature-folder.md:34-46`, `tests/unit/feature-tracked-files.test.ts:28-58`, `scripts/create-feature.ts:1703`, `:1778` | 없음(충돌 자체는 CHANGELOG 1105 절의 결정 대기) | — |
|
||||
| 1105/16-03 | 남음 · 결정 대기 | 남음 · 결정 대기(D11, `decisions.md:86`) [w2-fe-2 파일] | `scripts/lib/feature-scaffold-drill.ts:18-46` | 생성 기능 설치 상태로 브라우저 merge 게이트를 도는 장치 없음 · Low·P2 | D11 결정 뒤 |
|
||||
| 1105/16-04 | 일부 | 일부 [w2-fe-2 파일: `scripts/test-sample-removal.ts`가 부른다] | `scripts/lib/feature-residue.ts:61`(`iu` 부분 문자열), `:76-79`(`src` 경로+본문) | 완료 기준(`invoice-feature` rc=0)은 성립(E1: `src`에 `invoice-feature` 0건). 다른 합법 ID는 거짓 양성이다. `product-feature`: `src` 10파일, `tests` 이름 6개. `search` 31, `profile` 29, `items` 28, `account` 21 · Low·P3 | `src`도 이름 단위(경계, 대소문자 구분)로 찾는다(3절 1103/16-06 상세) |
|
||||
| 1103/11-02 | 일부 · 실행 환경 대기 | 일부 · runner로 확인 필요 | `.gitea/workflows/quality-gates.yml:140`, `:183`(글꼴 넷 설치) | 깨끗한 runner에서 `test:visual` 전부 통과(merge_browser job의 FE-GATE-008) | 코드 수정 없음. runner 결과 확인 |
|
||||
| 1103/11-03 | 일부 · 실행 환경 대기 | 일부 · runner로 확인 필요 [w2-fe-2 파일: 시험 timeout] | `tests/system/ci-runner/ci-artifact-contract.test.ts:65`, `:70`, `:462`, `:540`, `:1121` | `-t 'kills descendants'` 단독, 부하 5회는 namespace 허용 호스트가 있어야 돈다 | 코드 수정 없음. runner 확인 |
|
||||
| 1103/11-04 | 일부 · 실행 환경 대기 | 일부 · 실행 환경 대기 | `scripts/run-and-validate-provider.ts:278-293` | worktree에서 `test:system`. namespace 허용 호스트 + worktree가 필요하다. runner의 깨끗한 checkout으로는 답이 안 나온다 | 코드 수정 없음 |
|
||||
| 1103/12-05 | 일부 · 결정 대기 | 고쳐짐 | 명령 안 경로 `scripts/verify-documentation-readiness.ts:302-330`, 짝 링크 pin 대조, 살아 있는 문서 전부 `:342-347`(`livingDocuments`). 원장 행 `docs/operations/adapter-remediation-ledger.md:78-79`가 "지웠다"고 적는다 | 완료 기준(D1 실패, D2 보고) 성립. "1절 밖 문서"는 문서 체계 정리(PR #15)로 결정이 났다. 목표 설계는 `docs/design/`(기록)로 갔고 살아 있는 문서는 모두 검사한다. 지운 심볼은 1103 리뷰가 버린 대안 | — |
|
||||
| 1103/13-03 | 일부 · 결정 대기 | 일부 · 결정 대기(D1, `decisions.md:83`) | `package.json:135-136`(`react-router-dom` 7.18.1, `zod` 4.4.3), `pnpm-lock.yaml:2376`, `:2816`, `docs/operations/ci-quality-gates.md:519`(재확인 2026-12-04) | 운영 high 2건 · Medium·P2. 새 사실: 템플릿 초기 JS 194,403 B라 zod +약 7 KB는 템플릿 자체로는 예산 안이다. 드릴 기준으로는 아마 넘는다(추론) | D1 결정 때 이 숫자로 다시 본다 |
|
||||
| 1103/14-02 | 일부 · 결정 대기 | 일부 · 결정 대기(색인 없음) | `CHANGELOG.md:338-345` | memento 모양 `check:registries` 미실행. 자리 없는 파일을 템플릿에 들일지 결정 대기 · Medium·P1(원래) | 결정을 `decisions.md` 3.1에 올린다(PB-N1) |
|
||||
| 1103/15-02 (+1106 16.4) | 고침 / 재발 | 고쳐짐 | `docs/operations/performance-evidence.md:20-24`, `:223-226`이 숫자 대신 기록을 가리킨다 | 없음 | — |
|
||||
| 1103/16-06 | 일부 · 결정 대기 | 일부 · 결정 대기(색인 없음) | `scripts/create-feature.ts:582-583`, `scripts/create-feature-write-slice.ts:134-135`, `docs/manual/01-add-a-feature.md:432` | 읽는 곳 없는 필수 칸 · Low·P3. 덧붙임: `:432`의 "lab 측정(플랫폼 라우트만)"은 틀렸다. `labFeatureRoute`가 기능 라우트의 `navigationLabel`·`title`을 읽는다(`lab-performance.ts:55-68`, `test-performance.ts:263-267`) · Low·P3 | 문장 고침은 지금. 칸 정리는 결정 뒤 |
|
||||
| 1101/10-07 | 일부 | 일부 | `tests/unit/browser-rpc/browser-rpc-remediation.test.ts:389`, `:412`, `:588`(시계를 넘기지 않음). 이번 unit junit 1.029 s, 1.062 s, 1.060 s(E3) | 5개 중 3개가 100 ms를 넘는다 · Low·P3 | 3절 상세 |
|
||||
| 0929/12-03 | 일부 | 일부 | `.dependency-cruiser.json:302-312`(to `^src/adapters/`뿐). feature 규칙(`:118` 등)에 `support/`·`contracts/` 출발 규칙 없음 | 계층 밖 폴더 → 자기 `adapters/` → `src/adapters`의 두 단계 길 · Low·P2(원래 Medium, 직접 간선이 막혀 범위가 좁다) | 3절 상세 |
|
||||
| 0929/14-01 | 일부 | 고쳐짐 | `git ls-files artifacts` = `.gitkeep` 둘. `.gitignore`의 `artifacts/*` 블록, `tests/unit/tracked-artifacts.test.ts`, 삭제 `85f941c4` | 없음(새 worktree의 `git status`는 무시 규칙으로 본다, E1) | — |
|
||||
| 0929/14-02 | 일부 | 일부 | `README.md:277`("범위를 다 받으면 그 끝으로 옮긴다") vs `:279`("태그까지 따라잡았으면 `.template-origin`을 고친다"). `:277`이 기준점 형식 둘을 허용한다 | 기준점 형식 하나가 아니다. 두 문장이 언제 옮기는지 다르게 말한다. 명령 미실행 · Low·P3 | 3절 상세 |
|
||||
| 0929/14-03 | 일부 | 일부 | `docs/manual/03-outside-feature-folder.md:112-222`(C·D절이 사실상 표). `README.md`에 그 표나 링크가 없다. 샘플 삭제 안내는 샘플이 없어 해당 없음 | README 표(또는 정본 링크) 없음. 다음 동기화의 충돌 경로 대조 없음 · Low·P3 | 3절 상세 |
|
||||
| 0929/14-06 | 남음 · 결정 대기 | 남음 · 결정 대기(색인 없음) | `README.md:281`, `CHANGELOG.md:345`, `:305` | 받는 곳(이슈/FOLLOW-UP)과 상태 칸 없음 · Low·P3 | 결정을 색인에 올린다 |
|
||||
| 1101/14-07 | 남음 · 결정 대기 | 고쳐짐 | 문서 체계: `docs/README.md:14-80`(폴더가 수명을 정한다), 기록 머리 블록과 상태 검사 `scripts/lib/docs-system.ts:66-74`, `:318-334`. roadmap·capability-review가 `docs/design/`에 있다 | 결정은 design-docs `conventions/docs-system.md` 적용(PR #15, 2026-11-08)으로 났다. `decisions.md` 색인에는 없다(PB-N1) | — |
|
||||
| 1101/10-05 | 남음 · 결정 대기 | 남음 · 결정 대기(색인 없음) [w2-fe-2 파일: 계층을 옮기면 `config/ci/**`] | 이번 unit junit: 219파일 203.1 s. `scripts/`를 import하는 83파일이 173.5 s(85%)다. 분류가 1106과 달라 직접 비교는 못 한다. 큰 것: `documentation-readiness` 36.4 s, `product-extension-typecheck` 24.1 s, `manual-code-blocks` 23.2 s | 더 커졌다 · Low·P3(제안) | 결정 뒤 |
|
||||
| 1101/10-06 | 남음 · 결정 대기 | 남음 · 결정 대기(색인 없음) [w2-fe-2 파일] | `config/ci/gates.json` FE-GATE-005(`test-unit`+`test-coverage`), FE-GATE-020 드릴. 샘플 제거는 이제 SKIP(`scripts/test-sample-removal.ts:72-81`) | 한 merge에 `tests/unit` 13 → 약 9번(추론, FE-GATE-020 로그로 확인 필요) · Low·P3 | 결정 뒤 |
|
||||
| 1101/10-08 | 남음 · 결정 대기 | 남음 · 결정 대기(색인 없음) | `scopeSnapshot` 공유 2 + 사본 3(`tests/integration/http-execution-v3-auth-profile.test.ts:41`, `-live-authority.test.ts:23`, `-observability.test.ts:24`). `as never` 9곳, `deferred()` 7벌 | 조금 줄었다(참조 기능 테스트 삭제) · Low·P3 | 결정 뒤 |
|
||||
| 0929/12-07 | 남음 · 결정 대기 | 남음 · 결정 대기(색인 없음) [w2-fe-2 파일: `config/ci/ungated-*.json`] | `scripts/lib/ungated-scripts.ts:19-31`, `scripts/lib/ungated-tests.ts:20-31`. 두 JSON의 칸이 `script`/`path`·`reason`뿐 | owner·revisit 칸 없음 · Low·P3 | owner 값 결정 뒤 |
|
||||
| 0929/12-01 | 남음 | 남음 | `scripts/check-request-fanout.ts:23`, `:109`, `:172-179`(실패 줄에 탈출 방법·억제 수 없음), 허용 fixture는 `bulk-read.ts` 하나 | 0929 결정 (가)를 하지 않았다 · Medium·P2 | 3절 상세 |
|
||||
| 0929/12-04 | 남음 | 해당 없음 | 기준선과 개수 단언 삭제 `f6b2b96c`(소유자 결정 2026-11-07). `tests/unit/task3-selective-integration.test.ts:186-188` | 두 사본이 둘 다 없어졌다. 결정은 `decisions.md` 색인에 없다(PB-N1) | — |
|
||||
| 0929/12-05 | 남음 | 남음 [w2-fe-2 파일] | `package.json:157`, `pnpm-lock.yaml:84`, `:1654`. import 0건, `scripts/check-architecture.ts:104-106` | 실행하지 않는 의존성 · Low·P3 | w2-fe-2가 지운다. 3절 상세 |
|
||||
| 0929/12-06 | 남음 | 남음 [w2-fe-2 파일: 판정 결과가 `config/ci/ungated-tests.json`] | `scripts/lib/ungated-tests.ts:18`(`test\|spec`), `:94-95`(폴더 접두어). 지금은 main 단계 FE-GATE-029의 `check:ci:gating` | Vitest 폴더의 `*.spec.ts`를 게이트 안으로 센다 · Low·P3 | 3절 상세 |
|
||||
| 1101/12-03 | 남음 | 일부 | B1(대문자 `OKLCH`)은 잡힌다(`scripts/lib/design-system-rules.ts:68` `gi`, `bbde570`에도 있었다). 나머지: CSS 대상이 토큰 셋과 `styles/**`뿐(`scripts/check-design-system.ts:24-26`, `:44-48`), TSX는 hex·`oklch(`·`rgb(`만(`:146`), gradient·`outline-offset` 규칙 없음 | B2·B3·B7·B8·B9·B14 probe가 통과할 것(E1) · Low·P3 | 3절 상세 |
|
||||
| 1101/15-01 | 고쳐짐 | 고쳐짐 | FE-GATE-012가 merge에 있다(`config/ci/gates.json` stages). 이번 실행 PASS. 문서는 기록을 가리킨다(`performance-evidence.md:20-24`) | 없음(여유는 이제 12,445 B. 1106/15-01 행이 본다) | — |
|
||||
| 1101/15-03 | 남음 | 남음 | `scripts/check-bundle.ts:49-56`(초기 JS 파일만 합한다), `performance-evidence.md:94` | CSS 예산 없음, 라우트 단위 lazy 합 없음 · Low·P3 | 3절 상세 |
|
||||
| 1101/15-04 | 일부 | 일부 [w2-fe-2 파일: `tests/setup.ts`] | `tests/setup.ts:1`, `:4`(jest-dom·RTL 전역). 자식 프로세스 unit 파일이 그대로다. RPC 1 s 셋(1101/10-07) | 셋이 다 남았다 · Low·P3 | 3절 상세 |
|
||||
| 0929/11-04 | 남음 | 남음 | `scripts/test-performance.ts:244`, `:257`, `:275`, `:300`(부하는 기록만) | 부하로 판정이 뒤집힌다 · Medium·P2. 이제 runner가 있어 같은 빌드 10회 실험을 할 수 있다 | 3절 상세 |
|
||||
| 1101/16-05 | 남음 | 남음 | `src/presentation/boundaries/render-error-boundary.tsx:89`, `src/platform/errors/feature-error-boundary.tsx:12`, 둘 다 `src/presentation/routes/app-router.tsx:421`, `:625`에서 쓴다. `TelemetryPort` 두 타입(`src/platform/telemetry/telemetry-port.ts:10`, `src/application/ports/telemetry-port.ts:5`). `src/application/result.ts:9`는 소비자 0 | 셋 다 남았다(`ApiFailure` 조건만 성립) · Low·P3 | 3절 상세 |
|
||||
| 1101/16-06 | 남음 | 남음 | `scripts/create-feature.ts:340`(`contracts/<base>-mapper.ts`), `:346`(`contracts/<base>-message-catalog.ts`), `docs/manual/reference/create-feature.md:49-52`. 기능 `contracts/` 출발 규칙 없음 | 생성기가 퍼뜨린다 · Low·P3 | 3절 상세 |
|
||||
| 0929/11-02 | 남음 | 남음 | `scripts/drill-runbook.ts:249`, `:355`, `:397`, `:438`, `:554`. 입력은 runbook ID와 `--release-root`뿐(`:523-527`). `docs/operations/ci-quality-gates.md:409-412` | provider 확인이 필요한 drill이 어떤 입력으로도 PASS가 못 된다. production·field 단계는 닫힐 수 없다 · Medium·P2 | 3절 상세 |
|
||||
| 0929/11-05 | 남음(미검증) | 고쳐짐 | `config/scale/feature-shape-growth.json:3`(2026-11-08), `:15-18`(`source.commit` `e3c8db48`, 수정 파일 없음). `e3c8db48..5250ff95`의 `src`·생성기 변경은 주석과 수동 a11y 기록 경로뿐(`git diff --stat`) | 이번에 다시 재지는 않았다. `9c87cc4d` 본문이 "두 반복의 컴파일러 수치가 같다"고 적는다 | — |
|
||||
| 0929/11-07 | 남음 | 남음 | `tests/e2e/support/fixture-builds.ts:35`, `:47`, `tests/e2e/support/service-worker-builds.ts:103`, `:169` | `run`·한 번 치환이 두 벌 · Low·P3 | 3절 상세 |
|
||||
| 1101/13-03 | 남음 | 남음 [w2-fe-2 파일: 생성 workflow·`config/ci/**`] | 요구 주석은 merge_test에만 있다(`.gitea/workflows/quality-gates.yml:80-81`). provider job `:295-298`, `:341-344`에는 없다. provider 없는 배포 절 없음(`docs/operations/ci-quality-gates.md` grep 0) | Medium·P2 | 3절 상세 |
|
||||
| 0929/13-02 | 남음 | 남음 | `vite.config.ts:19`(`loadEnv`는 미선언 거절만), `:193-194`(`process.env`), `scripts/generate-build-manifest.ts:42-45`, `vite.service-worker.config.ts:61-62`, `.env.example:14` | `.env.local`로 준 빌드 변수가 번들과 스크립트에서 갈린다 · Medium·P2 | 3절 상세 |
|
||||
| 0929/13-03 | 남음 | 남음 | `scripts/generate-build-manifest.ts:70-77`(`entry.name === runtime?.moduleId`). 메시지 `Missing built route chunk`에 이유가 없다 | Medium·P2 | 3절 상세 |
|
||||
| 0929/13-04 | 남음 | 남음 | CSP 5벌: `config/hosting/security-headers.json:4`, `tests/fixtures/hosting/response-headers.json:7`, `:17`, `:27`, `:42`(문서 사본은 사라졌다). `scripts/check-browser-security.ts`에 CSP 검사 0건 | Low·P2 | 3절 상세 |
|
||||
| 0929/13-05 | 남음 | 남음 | `scripts/lib/supply-chain.ts`에 `deduped` 0건. `config/security/dependency-baseline.json:5778-5781` `scheduler` `scope: development` | Low·P2 | 3절 상세 |
|
||||
| 0929/13-06 | 일부 | 일부 | `scripts/lib/hosting-probe.ts:470-473`(루트가 아닌 URL 거절). SW 쪽은 `vite.service-worker.config.ts:105`로 고쳐졌다 | 하위 경로 배포에서 live probe를 쓸 수 없다 · Low·P3 | 3절 상세 |
|
||||
| 0929/13-10 | 남음 | 남음 | `README.md:281`(선택 기능·설정을 바꿔 재현되는 경우를 적지 않는다) | Low·P3 | 3절 상세 |
|
||||
| R-2 | 남음 | 남음 | 빌드 ID 기본값이 일곱 곳이다: `src/contracts/env.ts:54`, `:204`(`\|\|`), `scripts/generate-runtime-config.ts:75`(`\|\|`)·`:76`(`??`), `scripts/generate-build-manifest.ts:42-44`(`??`), `vite.service-worker.config.ts:61-62`(`??`), `scripts/verify-reproducible-build.ts:65-67`(`??`), `scripts/lib/build-environment.ts:56-58` | 다섯 곳 → 일곱 곳 · Low·P3(제안) | 3절 상세 |
|
||||
| 1106/14-01 | 고침 | 고쳐짐 | `CHANGELOG.md:230-232`. 두 절의 TechLog 서술이 맞는다(`:230`, `:348`) | 없음(`as` 단언 쪽은 커밋이 적은 추론) | — |
|
||||
| 1106/10-01 | 고침 | 고쳐짐 | `tests/unit/playwright-capabilities-run-isolation.test.ts`, 드릴이 이름으로 지운다(`scripts/test-browser-file-storage-runtime-removal.ts:140`). `tests/unit/vite-build-inputs.test.ts:16-21`(소비자 고정 목록, `existsSync` 거르기 없음) | 16.4절의 남은 것(측정 스크립트 존재 조건)도 없어졌다 | — |
|
||||
| 1106/11-01 | 고침 | 고쳐짐 | `scripts/lib/a11y-data-state.ts:17-22`, `tests/unit/a11y-report.test.ts:136-186` | 16.4절의 남은 것(`paramsSchema`가 GET 입력과 다른 상세 페이지)은 그대로. 지금 템플릿에는 그런 라우트가 없다 | — |
|
||||
| 1106/12-01 | 고침 | 고쳐짐 | `scripts/lib/removal-fixture.ts:66-80`(`backend-contract-pin-document.test.ts`로 뗐다), `tests/unit/removal-fixture.test.ts:190-207`(코드 안 문서 경로를 본다) | 판정이 파일 단위인 것은 그대로 | — |
|
||||
| 1106/12-02 | 고침 | 고쳐짐(게이트 단위) | `scripts/lib/run-isolation.ts:93-110`, `scripts/check-bundle.ts:29-33`, `scripts/generate-supply-chain.ts` | 스크립트 단위로는 남았다. `check-app-build-input.ts:88`, `check-optional-recipes.ts:38`, `lib/release-candidate.ts:104`, `verify-reproducible-build.ts:25`가 루트를 읽고 스스로 거절하지 않는다. 게이트 안에서는 거절하는 단계가 앞이나 같은 명령에 있어 게이트가 거짓 PASS하지는 않는다. `verify:reproducible-build` 단독 실행은 이전 빌드를 두 번 재서 PASS를 쓸 수 있다(E1) · Low·P3 | 3절 상세 |
|
||||
| 1106/13-01 | 고침 | 고쳐짐 · runner로 확인 필요 | `config/ci/gates.json:1971-1976`(scan → admission), `docs/operations/ci-quality-gates.md:154-160`, `:491-506` | runner의 release run upload 미확인 | — |
|
||||
| 1106/14-02 | 고침 | **재발** | `git log --format=%B bbde570..HEAD`: `121e1125`·`429b8d88`·`0805910c` 본문이 `30a379f`를, `9c87cc4d` 본문이 `8c4b09b7`을 가리킨다. 둘 다 원격 브랜치에 없는 다시 짓기 전 커밋이다(트리가 `121e1125`·`e3c8db48`과 같다). CHANGELOG 새 절의 해시 102개는 모두 조상이다 | 대조 단계가 리뷰 라운드 통합에만 묶였다(`CHANGELOG.md:12`). 정리 PR(#11·#12) 통합은 대조를 하지 않았다 · Low·P3 | 3절 상세 |
|
||||
| 1106/15-01 | 고침(D9) | 일부 · 결정 재검토(D9, 새 증거) | `config/performance/budgets.json:4` 206,848. 이번 FE-GATE-012 194,403 B. `config/scale/feature-shape-ceilings.json`의 `initialJavascript`(194,354 / 17 / first 6,327 / per 539 / ctx 4). 규칙 `performance-evidence.md:54-62`, "다시 볼 때" `:50-53` | D9 규칙으로 계산하면 드릴 약 201.3 KB(추론) → 예산 약 198 KiB다. 지금 값은 4 KiB 크다. 템플릿 여유는 12,445 B다. "다시 볼 때"에 "기준선이 줄 때"가 없다. 규칙을 묶는 테스트도 없다 · Low·P3 | 3절 상세 |
|
||||
| 1106/16-01 | 고침 | 고쳐짐 | `scripts/lib/feature-residue.ts:18-35`, `:66-73`, `:86-87`, `tests/unit/feature-residue.test.ts:65-127`, `docs/manual/01-add-a-feature.md:791-793`("못 잡음") | 한 단어 ID·URL만 적은 spec은 "못 잡음"으로 적혀 있다(완료 기준의 둘째 길) | — |
|
||||
|
||||
## 3. 남음·일부·재발 행별 상세
|
||||
|
||||
각 행은 지금 등급 · 근거 보충 · 최소 개선 방향 · 완료 기준 · RED 시험 순서다. 결정 대기는 이유만 적는다.
|
||||
|
||||
### 3.1 1105/10-03 — 남음(제안)
|
||||
- 고칠 수 없는 이유: 판정 규칙 모듈에 변이 도구를 들이는 것은 dev 의존성 추가다. 공급망 증거(`config/security/dependency-change-evidence.json`)와 실행 비용이 따르는 소유자 결정이다. 결함이 아니라 개선 제안이다(`review-criteria.md` 2절 밖).
|
||||
- 방향: 들일지 말지 결정한다. 안 들이면 그 결정과 이유를 `decisions.md`에 적고 행을 닫는다.
|
||||
|
||||
### 3.2 1105/12-01 (+11-02) — 일부 · runner로 확인 필요
|
||||
- 지금 등급: ① 확인 대기(등급 없음). ② Low·P3, 작은 진단 누락.
|
||||
- ①: D8(2026-11-12)대로 desktop의 FE-GATE-013 실패는 merge 판정에서 뺀다. 「충족」은 조건을 갖춘 runner에서만 센다. merge_test job(`quality-gates.yml:77-120`)의 FE-GATE-013 결과가 답이다.
|
||||
- ② 근거: `waitForFileContent`·`waitForExistingPath`(`ci-artifact-contract.test.ts:1774-1813`)는 파일 이름만 적고 던진다. provider가 bwrap 오류로 바로 끝나도 "did not reach expected content"만 남는다. 1105/11-02 개선 방향의 "파일 대기 test가 provider stderr를 붙인다"가 들어오지 않았다. 시험 timeout을 바꾸는 w2-fe-2 작업과 같은 파일 근처일 수 있다.
|
||||
- 최소 개선: 대기 함수가 `execution`(child, stderr 버퍼)을 받는다. 시간 초과 때 `stderr`의 마지막 몇 줄과 종료 코드를 메시지에 붙인다. 이미 끝난 child면 기다리지 않고 바로 던진다.
|
||||
- 완료 기준: provider 명령이 즉시 실패하는 fixture에서 시험 실패 메시지에 그 stderr 한 줄이 나온다.
|
||||
- RED: `tests/system` 밖에서도 도는 helper 단위 시험이다. `process.stderr.write('bwrap: boom'); process.exit(1)`인 child를 넘기고 `waitForFileContent`가 `/bwrap: boom/`을 담아 던지는지 본다. 지금은 메시지에 stderr가 없어 실패한다.
|
||||
|
||||
### 3.3 1105/12-04 — 일부 · 결정 대기(D6)
|
||||
- 이유: 게이트 출력 경로를 실행 단위로 나눌지, "한 checkout 한 실행"을 계약으로 둘지는 D6(프론트 소유자)다. 지금은 `README.md:221`(M1)와 `verify.sh` `flock`이 막는다.
|
||||
|
||||
### 3.4 1105/13-01 — 일부 · runner로 확인 필요
|
||||
- 남은 것은 실행뿐이다. `workflow_dispatch stage=release` run 하나의 artifact `immutable-gate-evidence-*`에 7경로가 있는지 본다. 일부러 거절시킨 run(`RELEASE_TARGET=production` + 예시 endpoint)도 하나 본다. 업로드 action이 여러 줄 `path`에서 없는 파일을 건너뛰는지도 거기서 본다.
|
||||
|
||||
### 3.5 1105/15-04 — 재발 · 결정 대기(두 묶음)
|
||||
- 지금 등급: Low·P2(원래와 같다). 13·14번 관점, 규모 축의 측정 공백이다.
|
||||
- 근거:
|
||||
- `bbde570`에서는 예제 기능의 `EXAMPLES_UI`가 lab 대상이었다.
|
||||
- `e3c8db48`이 예제를 지웠다. `labFeatureRoute`는 공개·내비게이션 라우트만 고른다(`lab-performance.ts:59-64`). 생성기는 목록·쓰기 라우트를 모두 `session-required`로 만든다(`create-feature.ts:578`, `create-feature-write-slice.ts:130`).
|
||||
- 그래서 템플릿에서도, 생성 기능만 가진 제품에서도 `featureRoute`는 `measured: false`다(`test-performance.ts:342-344`). 문서도 그렇게 적는다(`performance-evidence.md:126-128`).
|
||||
- 1105/15-04의 근거 "다운스트림 화면은 모두 기능 라우트다"와 완료 기준 "`lab.json`에 기능 라우트 시간과 표본"이 다시 어긋난다.
|
||||
- 결정 대기인 것: 진입 요청 두 묶음을 하나로 줄이는 일(`performance-evidence.md:134-137`)뿐이다.
|
||||
- 최소 개선(둘 중 하나):
|
||||
- (a) lab이 세션이 있는 라우트도 고른다. local 프로필의 개발 세션이나 lab 전용 고정 세션을 쓴다.
|
||||
- (b) FE-GATE-026이 생성 기능 하나를 사본에 설치하고 그 목록 라우트를 잰다. FE-GATE-020이 쓰는 drill 방식이다.
|
||||
- 완료 기준: 템플릿 그대로의 FE-GATE-026 실행에서 `lab.json`의 `context.sampling.featureRoute.measured`가 true이고, 생성 기능 라우트의 표본 5개가 있다.
|
||||
- RED: `tests/unit/lab-performance.test.ts`에 시험 하나를 더한다. `planFeature`(`create-feature.ts`)가 만든 라우트 표와 소유자 표를 `labFeatureRoute`에 넘기면 null이 아니어야 한다. 지금은 `session-required`라 null이 나와 실패한다.
|
||||
|
||||
### 3.6 1105/16-03 — 남음 · 결정 대기(D11) [w2-fe-2 파일]
|
||||
- 이유: 생성 기능 설치 상태로 FE-GATE-008·009를 merge에서 돌릴지는 D11(템플릿 담당)이다. 드릴 제외 목록(`feature-scaffold-drill.ts:18-46`)이 지금 그 사실을 적는다.
|
||||
|
||||
### 3.7 1105/16-04 — 일부 [w2-fe-2 파일: 호출자 `scripts/test-sample-removal.ts`]
|
||||
- 지금 등급: Low·P3. 원래 Low·P2였다. 매뉴얼 예시 이름은 통과하므로 범위가 좁다.
|
||||
- 근거: `src`는 `new RegExp(names, "iu")`로 경로+본문 전체에서 부분 문자열을 찾는다(`feature-residue.ts:61`, `:76-79`). `create-feature.ts`가 받는 ID 중 `product-feature`는 템플릿 `src` 10파일에 걸린다. 걸리는 이름: `src/contracts/product-features.ts`, `src/application/ports/product-features-port.ts`, 그것을 import하는 파일들, `src/presentation/examples/platform-overview-page.tsx`, `src/apps/AGENTS.md`. 한 단어 ID(`search`, `profile`, `items`, `account`)는 21~31파일에 걸린다. 1106 FR-04가 같은 원인이다.
|
||||
- 최소 개선: `src` 본문도 `tests` spec처럼 이름 단위(대소문자 구분, 앞뒤 `[A-Za-z0-9_-]` 없음)로 찾는다. 경로는 세그먼트 일치로 본다(`src/features/<id>/`, 파일 이름이 `<id>`로 시작). 생성 색인 `src/.generated/*`는 드릴이 다시 만든 뒤 본다.
|
||||
- 완료 기준: `create:feature product-feature` 뒤 `test:sample-removal -- --feature=product-feature`가 rc=0이다. `src/contracts/leftover.ts`에 `"product-feature"`를 남긴 변이는 실패한다. `invoice-feature`는 계속 통과한다.
|
||||
- RED: `tests/unit/feature-residue.test.ts`에 시험을 더한다. 템플릿 `src` 사본에서 `productFeatureResidue(root, "product-feature", "product-feature")`가 `[]`여야 한다. 지금은 10파일이 나와 실패한다.
|
||||
|
||||
### 3.8 1103/11-02 · 11-03 · 11-04 — 일부 · runner로 확인 필요 / 실행 환경 대기
|
||||
- 셋 다 코드 수정은 들어와 있고 실행만 남았다.
|
||||
- 11-02: merge_browser job의 FE-GATE-008에서 `visual fonts match the goldens`를 포함한 `test:visual` 전부 통과를 본다.
|
||||
- 11-03 [w2-fe-2 파일]: namespace를 허용하는 runner가 있어야 한다. w2-fe-2가 시험 timeout을 바꾸므로 그 뒤의 값으로 본다.
|
||||
- 11-04: worktree(`.git`이 파일)에서 돌아야 한다. runner의 깨끗한 checkout으로는 답이 안 나온다.
|
||||
|
||||
### 3.9 1103/13-03 — 일부 · 결정 대기(D1)
|
||||
- 이유: 운영 의존성 갱신은 owner와 다른 reviewer가 필요하다(`ci-quality-gates.md:525-526`).
|
||||
- 결정에 쓸 새 숫자: 템플릿 초기 JS 194,403 B다. zod +약 7 KB는 템플릿 자체로는 예산 206,848 B 안이다. 생성 기능 둘을 더한 드릴(약 201.3 KB, 추론)에서는 넘을 수 있다. FE-GATE-020 값으로 확인해야 한다.
|
||||
|
||||
### 3.10 1103/14-02 · 0929/14-06 · 1103/16-06 · 1101/10-05 · 10-06 · 10-08 · 0929/12-07 — 결정 대기(색인 없음)
|
||||
- 이유는 1106 README 13.1절과 같다(파일 이동·gates 구조·owner 값·제품 소유 자리).
|
||||
- 다만 7건 모두 `decisions.md` 3.1절 표에 없다. 1105/15-04의 두 묶음까지 더하면 8건이다. 그 문서의 규칙대로라면 결정 대기가 아니라 미완이다(PB-N1).
|
||||
- 1103/16-06의 문장 하나는 결정과 따로 지금 고칠 수 있다.
|
||||
- 근거: `docs/manual/01-add-a-feature.md:432`의 "lab 측정(`scripts/test-performance.ts`, 플랫폼 라우트만)이 읽는다"가 틀렸다. `labFeatureRoute`는 기능이 소유한 공개 라우트의 `navigationLabel`·`title`을 읽는다(`test-performance.ts:263-267`).
|
||||
- 등급: Low·P3.
|
||||
- 방향: "lab은 기능이 소유한 공개 내비게이션 라우트의 두 칸을 읽는다. 생성 라우트는 `session-required`라 읽히지 않는다"로 고친다.
|
||||
- 완료 기준: 문장이 코드와 같다.
|
||||
- RED: 해당 없음(문서). 원하면 `labFeatureRoute` 소유자 조건을 문장과 대조하는 문서 시험을 둔다.
|
||||
- 1101/10-05 · 10-06 · 0929/12-07을 고치면 `config/ci/**`가 바뀐다 [w2-fe-2 파일].
|
||||
|
||||
### 3.11 1101/10-07 — 일부
|
||||
- 지금 등급: Low·P3.
|
||||
- 근거: "cancels the physical stream exactly once after a timeout"(`:389`), "refuses a second stream while the first has not confirmed closure"(`:412`), "admits a second stream once waitClosed fulfils"(`:588`)가 `clock`을 넘기지 않는다. 이번 junit에서 1.029 s, 1.062 s, 1.060 s다. 1초 대기는 runtime 기본 시계에서 온다. 같은 파일의 `cappedClock`(`:550-566`)은 다른 테스트 넷에만 넘긴다.
|
||||
- 최소 개선: 세 테스트에도 `cappedClock`(또는 fake timer)을 넘긴다. 작업 마감 25 ms(`:386-387`)는 그 아래라 단언 뜻이 바뀌지 않는다.
|
||||
- 완료 기준: 세 테스트가 각각 100 ms 아래다(junit).
|
||||
- RED: 세 `it`에 `{ timeout: 300 }`을 준다. 지금은 1 s를 자서 시간 초과로 실패하고, 시계를 넘기면 통과한다. 상한은 그대로 둔다.
|
||||
|
||||
### 3.12 0929/12-03 — 일부
|
||||
- 지금 등급: Low·P2. 원래 Medium·P2였는데 직접 간선은 막혀 범위가 좁다.
|
||||
- 근거:
|
||||
- `feature-and-app-roots-do-not-reach-adapters`의 to는 `^src/adapters/`뿐이다(`.dependency-cruiser.json:302-312`).
|
||||
- 기능의 `support/`·`contracts/`·`hooks/` 같은 계층 밖 폴더에서 자기 `adapters/`로 가는 간선을 막는 규칙이 없다. presentation → `support/`도 막지 않는다.
|
||||
- 그래서 `presentation → support/x.ts → ../adapters/<gateway>.ts → src/adapters/http`가 통과한다(1106 12-R3과 같은 모양, E1). 템플릿에는 기능이 없어 지금 이 길을 쓰는 코드는 없다.
|
||||
- 최소 개선: 출발 `^src/features/[^/]+/(?!(domain|application|contracts|adapters|presentation)/)`인 파일을 금지한다. 계층 밖 폴더 자체를 없애는 규칙이고, `src/features/AGENTS.md`의 "다섯 폴더"와 같다. 또는 그 폴더에서 자기 `adapters/`로 가는 간선을 금지한다.
|
||||
- 완료 기준: 12-R3 probe(생성 기능 + `support/gateway-reexport.ts` + presentation 재수출)에서 `check:architecture`가 실패한다. 규칙 주석과 동작이 같다.
|
||||
- RED: `scripts/check-architecture.ts`의 그래프 fixture(`:823-840` 근처)에 두 단계 재수출 fixture를 더하고 "거절되어야 한다"고 적는다. 지금은 통과해서 fixture 검사가 실패한다.
|
||||
|
||||
### 3.13 0929/14-02 — 일부
|
||||
- 지금 등급: Low·P3.
|
||||
- 근거: `README.md:277`은 기준점을 `.template-origin` 또는 제품 잠금 파일에 두게 한다(형식 둘). 그리고 "범위를 다 받으면 그 끝으로 옮긴다"고 한다. `:279`는 "태그까지 따라잡았으면 `.template-origin`을 고친다"고 한다. 범위만 받았을 때 `.template-origin`을 옮기는지 두 문장이 다르게 읽힌다. 범위 반영 명령(`:273-274`)도 실행한 기록이 없다.
|
||||
- 최소 개선: 기준점 형식을 `.template-origin` 한 줄(전체 SHA + 날짜) 하나로 정한다. 제품 잠금 파일은 "그 값을 옮겨 적는 곳"으로 둔다. `:277`·`:279`는 "범위든 태그든 받은 끝 커밋으로 옮긴다" 한 문장으로 합친다. 형식을 하나로 강제할지가 다운스트림(tech-log)을 바꾸는 일이라 소유자 확인이 필요하면 그렇게 적는다.
|
||||
- 완료 기준: README에 기준점 형식이 하나이고, 언제 옮기는지가 한 문장이다.
|
||||
- RED: 해당 없음(문서). 대신 `README.md` 「원본 업데이트 반영」 절에 `.template-origin` 외 기준점 파일 이름이 없는지 보는 문서 시험을 둘 수 있다.
|
||||
|
||||
### 3.14 0929/14-03 — 일부
|
||||
- 지금 등급: Low·P3.
|
||||
- 근거: 제품이 고치는 템플릿 파일의 사실상 정본은 매뉴얼 03 C·D절(`docs/manual/03-outside-feature-folder.md:112-222`)이다. README 「원본 업데이트 반영」 절(`README.md:254-281`)은 그 표를 갖지도 가리키지도 않는다. 다음 동기화의 충돌 경로를 표와 맞춰 본 기록이 없다.
|
||||
- 최소 개선: README 그 절에 "동기화 때 충돌하는 제품 소유 파일과 고치지 않는 템플릿 파일은 매뉴얼 03 C·D절이 정본이다" 한 줄과 링크를 둔다. 다음 다운스트림 동기화 기록에서 충돌 경로를 C·D절과 대조한다.
|
||||
- 완료 기준: README가 정본 표를 가리킨다. 다음 동기화의 충돌 경로가 모두 C·D절에 있다(그 동기화 때 확인).
|
||||
- RED: 문서 시험 하나. README의 그 절에 `docs/manual/03-outside-feature-folder.md` 링크가 있어야 한다.
|
||||
|
||||
### 3.15 0929/12-01 — 남음
|
||||
- 지금 등급: Medium·P2. 게이트가 탈출 방법을 숨긴다(`review-criteria.md` 2절 표).
|
||||
- 근거:
|
||||
- 0929 README 5절이 (가)를 권했고 `decisions.md:52`가 그 묶음을 정한 결정으로 색인한다. (가)는 "규칙 유지 + 실패 메시지에 예외 방법 + 커서 페이지네이션 허용 fixture"다.
|
||||
- 지금 실패 줄은 `FAIL <file>:<line> <call> inside <context>`뿐이다(`check-request-fanout.ts:172-175`).
|
||||
- 허용 fixture는 `bulk-read.ts` 하나다. 억제 수도 출력하지 않는다(`:177-179`).
|
||||
- 1105 README 16.6절의 "휴리스틱 재설계"는 (나)다. (가)는 작다.
|
||||
- 최소 개선: (가)를 한다.
|
||||
- 실패 줄에 두 탈출 경로를 적는다. 기능 `adapters/`에서 `createCursorPaginationRuntime` 조립, 그리고 같은 줄 `// fanout-reviewed: <이유>`다.
|
||||
- 허용 fixture에 주석 달린 커서 루프를 더한다.
|
||||
- 결과 줄에 억제된 호출 수와 위치를 적는다.
|
||||
- 머리 주석과 `ci-quality-gates.md`에 미탐 범위를 적는다.
|
||||
- 완료 기준: tech-log 모양 코드에서 메시지만 보고 두 방법을 안다. 허용 fixture에 주석 달린 커서 루프가 있다. 출력에 억제 수가 있다.
|
||||
- RED: `tests/unit`에 `findRequestFanout` 시험 둘을 더한다. 실패 메시지(또는 `main` 출력)가 `fanout-reviewed:`와 `createCursorPaginationRuntime`을 담는지, `--fixture` 실행이 주석 달린 커서 fixture를 허용으로 세는지 본다. 지금은 메시지에 없어 실패한다.
|
||||
|
||||
### 3.16 0929/12-05 — 남음 [w2-fe-2 파일]
|
||||
- 지금 등급: Low·P3.
|
||||
- 근거: `package.json:157` `"dependency-cruiser": "18.1.0"`, lockfile `:84`, `:1654`, `:4106`. import 0건이다. 검사기는 자기 그래프를 쓴다(`check-architecture.ts:104-106`).
|
||||
- 최소 개선: `pnpm remove dependency-cruiser`를 하고 의존성 기준선과 change evidence를 다시 승인한다. brief대로 w2-fe-2가 이 줄을 바꾸는 중이다.
|
||||
- 완료 기준: `package.json`과 lockfile에 없다.
|
||||
- RED: 개발 의존성마다 `scripts`·`src`·`tests`·설정 파일 어디선가 쓰이는지 보는 시험이 있으면 지금 실패한다. 없으면 "`package.json`에 `dependency-cruiser`가 없다" 한 줄 단언이다.
|
||||
|
||||
### 3.17 0929/12-06 — 남음 [w2-fe-2 파일]
|
||||
- 지금 등급: Low·P3. 지금 해당 파일은 0건이다(1105 16.6절).
|
||||
- 근거: `TEST_FILE = /\.(?:test|spec)\.tsx?$/u`(`ungated-tests.ts:18`)로 모은다. 그리고 `gated`는 Vitest 경로 접두어만 본다(`:94-95`). 그래서 `tests/unit/x.spec.ts`는 "게이트 안"이지만 Vitest include(`vitest.config.ts`의 `*.test.*`)에 안 걸려 돌지 않는다.
|
||||
- 최소 개선: Vitest 경로에서 온 gated 경로는 파일이 `.test.`일 때만 gated로 본다. Playwright `testDir`에서 온 경로는 `.spec.`만 본다. 경로마다 runner 종류를 기록하는 식이다.
|
||||
- 완료 기준: `tests/unit/probe.spec.ts`를 두면 `check:ci:gating`이 실패한다.
|
||||
- RED: `ungatedTestFailures({ testFiles: ["tests/unit/probe.spec.ts"], gatedPaths: ["tests/unit"], exclusions: [] })`가 실패 한 줄을 내야 한다. 지금은 `[]`라 실패한다. gated 경로에 종류 정보를 더하면 시그니처가 바뀐다.
|
||||
|
||||
### 3.18 1101/12-03 — 일부
|
||||
- 지금 등급: Low·P3. 지금 위반은 없다.
|
||||
- 근거: B1은 잡힌다(`design-system-rules.ts:68`). 아래 다섯은 지금도 통과할 것으로 본다(E1).
|
||||
- B2: `linear-gradient(in oklch, …)`. 규칙이 `color-mix`만 본다.
|
||||
- B3: TSX 인라인 `color-mix`. TSX 검사(`check-design-system.ts:146`)가 hex·`oklch(`·`rgb(`만 본다.
|
||||
- B7·B8: `styles/**`의 토큰 재정의. 정의는 집합으로만 모은다(`:54-58`).
|
||||
- B9: `outline-offset: 0`. 규칙이 없다.
|
||||
- B14: 기능 폴더 CSS. 대상이 토큰 셋과 `styles/**`뿐이다(`:24-26`, `:44-48`).
|
||||
- 최소 개선:
|
||||
- (1) hue 혼합 정규식을 `(?:color-mix|(?:linear|radial|conic)-gradient)\(\s*in\s+(oklch|lch|hsl|hwb)`로 넓힌다.
|
||||
- (2) TSX 검사에 같은 정규식을 쓴다.
|
||||
- (3) `src/**/*.css`를 모두 읽거나, `main.tsx`·`theme.css` 밖의 `.css` import를 그래프 규칙으로 막는다.
|
||||
- (4) 토큰 파일 밖 `:root` 재정의를 실패로 둔다.
|
||||
- (5) `outline-offset`이 0이면 대비 비교 목록에 action·danger를 넣거나 실패시킨다.
|
||||
- 완료 기준: B2·B3·B7·B8·B9·B14 probe가 모두 실패한다.
|
||||
- RED: `tests/unit/design-system-rules.test.ts`에 probe 소스 여섯을 넣고 각 규칙 함수가 실패 줄을 내는지 본다. 지금은 B1만 실패 줄이 나온다.
|
||||
|
||||
### 3.19 1101/15-03 — 남음
|
||||
- 지금 등급: Low·P3.
|
||||
- 근거: `check-bundle.ts:49-56`이 초기 JS 파일만 합한다. 문서도 "CSS는 예산에 들어가지 않는다"고 적는다(`performance-evidence.md:94`). 라우트 진입 하나의 lazy 합 예산도 없다.
|
||||
- 최소 개선:
|
||||
- `budgets.json`에 `initialCssGzipBytes`를 두고, 엔트리 `css` 필드의 gzip 합을 잰다.
|
||||
- 라우트별 "dynamic entry + 초기에 없는 정적 import" 합을 `bundle.json`에 남긴다. 예산은 값을 본 뒤 정한다.
|
||||
- 예산 값은 소유자 결정이다. 기록부터는 지금 할 수 있다.
|
||||
- 완료 기준: CSS가 예산 + 1 B면 `check:bundle`이 실패한다. 라우트별 합이 `bundle.json`에 있다.
|
||||
- RED: `tests/unit/check-bundle-output.test.ts`에 fixture manifest를 넣는다. 엔트리 CSS가 예산 + 1 B인 경우 실패해야 한다. 지금은 CSS를 안 봐서 통과하므로 시험이 실패한다.
|
||||
|
||||
### 3.20 1101/15-04 — 일부 [w2-fe-2 파일: `tests/setup.ts`]
|
||||
- 지금 등급: Low·P3.
|
||||
- 근거:
|
||||
- `tests/setup.ts:1`, `:4`가 모든 Vitest 파일에 jest-dom·RTL을 싣는다. DOM 없는 unit도 받는다.
|
||||
- 자식 프로세스 unit 파일이 `tests/unit`에 그대로다. 이번 junit 기준 `scripts/` import 83파일, 173.5 s. 2026-11-12 `91962e24`는 timeout만 정했다.
|
||||
- 실제 시계 대기 셋은 1101/10-07 상세다.
|
||||
- 최소 개선: setup이 `typeof document !== "undefined"`일 때만 DOM 도구를 싣는다. 파일 이동은 1101/10-05 결정과 겹치므로 결정 뒤에 한다.
|
||||
- 완료 기준(이 행에서 고칠 수 있는 몫): DOM 없는 unit 파일이 RTL을 읽지 않는다. 실제 시간을 기다리는 테스트가 없다.
|
||||
- RED: DOM 없는 unit 파일 하나에서 `globalThis` 또는 `vi.importActual` 흔적으로 `@testing-library/react`가 적재되지 않았는지 단언한다. 지금은 setup이 전역으로 싣기 때문에 실패한다.
|
||||
|
||||
### 3.21 0929/11-04 — 남음
|
||||
- 지금 등급: Medium·P2. release 판정의 신뢰도 문제다.
|
||||
- 근거: 부하는 `lab.json`에 기록만 한다(`test-performance.ts:244`, `:257`, `:275`, `:300`). 판정은 부하와 상관없다.
|
||||
- 최소 개선: 측정 전 `loadavg[0] / logicalCpus`가 기준을 넘으면 `UNVERIFIED`(exit 3)로 끝낸다. drill·hosting과 같은 3상태다. 기준값은 runner에서 잰 뒤 정한다.
|
||||
- 완료 기준: 같은 빌드를 부하를 바꿔 10회 돌려도 PASS·FAIL이 뒤집히지 않는다. 기준을 넘은 실행은 `UNVERIFIED`다.
|
||||
- RED: 부하 판정 함수를 `scripts/lib/lab-performance.ts`로 빼고 단위 시험을 둔다. `loadavg [24, …]`, `cpus 12`면 `UNVERIFIED`여야 한다. 지금은 함수가 없어 시험이 실패한다.
|
||||
|
||||
### 3.22 1101/16-05 — 남음
|
||||
- 지금 등급: Low·P3.
|
||||
- 근거:
|
||||
- 기능 경계 두 벌이 겹쳐 쌓인다(`app-router.tsx:421` `FeatureBoundary`, `:625` `FeatureErrorBoundary`).
|
||||
- `TelemetryPort` 이름이 두 타입을 가리킨다.
|
||||
- `src/application/result.ts`는 `@deprecated` 재수출이고 import 0건이다(`git grep application/result` = 주석 한 줄).
|
||||
- 최소 개선:
|
||||
- `src/application/result.ts`를 지운다.
|
||||
- `src/application/ports/telemetry-port.ts`의 타입을 `ApplicationTelemetryPort` 같은 다른 이름으로 바꾼다.
|
||||
- feature 수준 경계는 하나로 합치거나 역할 이름으로 나눈다.
|
||||
- 완료 기준: feature 수준 경계 컴포넌트가 하나다. `TelemetryPort` 이름이 한 타입만 가리킨다. `application/result.ts`가 없다.
|
||||
- RED: `tests/architecture`에 시험을 둔다. `src` 안 export 타입 이름 중 `TelemetryPort`가 한 파일에서만 나와야 한다. `src/application/result.ts`가 없어야 한다. 지금 둘 다 실패한다.
|
||||
|
||||
### 3.23 1101/16-06 — 남음
|
||||
- 지금 등급: Low·P3.
|
||||
- 근거: 생성기가 `contracts/<base>-mapper.ts`(뷰 값 변환)와 `contracts/<base>-message-catalog.ts`(화면 문구)를 쓴다(`create-feature.ts:340`, `:346`). 기능 `contracts/`에서 출발하는 규칙이 없다(feature 규칙 넷은 domain·application·presentation·adapters 출발).
|
||||
- 최소 개선:
|
||||
- 생성기가 mapper를 `application/`, 문구를 `presentation/`에 쓴다.
|
||||
- `feature-contracts-are-wire-only` 규칙을 둔다. 출발 `^src/features/[^/]+/contracts`, 금지 `src/(presentation|adapters|bootstrap)`, 기능 `presentation|adapters`, `react`다.
|
||||
- 매뉴얼 `reference/create-feature.md:49-52`를 고친다.
|
||||
- 완료 기준: 생성 기능 `contracts/`에 문구·뷰 모델이 없다. 규칙을 지우는 변이에서 architecture fixture가 실패한다.
|
||||
- RED: `tests/unit/create-feature.test.ts`에 단언을 더한다. `planFeature` 결과에 `contracts/` 아래 `-message-catalog.ts`·`-mapper.ts`가 없어야 한다. 지금은 있어 실패한다.
|
||||
|
||||
### 3.24 0929/11-02 — 남음
|
||||
- 지금 등급: Medium·P2. 운영 단계 게이트 전체가 쓸 수 없는 상태로 복제된다.
|
||||
- 근거:
|
||||
- FE-RB-002~005 drill은 `providerVerificationRequired: true`다(`drill-runbook.ts:249`, `:355`, `:397`, `:438`). 그래서 항상 `UNVERIFIED`(`:554`)다.
|
||||
- 입력은 runbook ID와 `--release-root`뿐이다(`:523-527`).
|
||||
- 문서는 "provider 증거가 없으면 production 단계는 닫히지 않는다. 의도한 결과다"라고 적는다(`ci-quality-gates.md:409-412`). 그러나 증거를 줄 길이 없다. 그래서 `field_gate`(`quality-gates.yml:520-523`)가 늘 막힌 `production_gate`에 묶인다.
|
||||
- 최소 개선(둘 중 하나):
|
||||
- (a) `--provider-evidence <record.json>` 입력. releaseId·전환 시각·smoke 결과·run id를 받고, 스키마와 releaseId가 맞으면 해당 항목을 PASS/FAIL로 바꾼다.
|
||||
- (b) production·field 단계를 "provider 연결 전까지 기본 꺼짐"으로 문서화한다. `field_gate`가 도달할 수 없는 선행 조건에 묶이지 않게 한다. 단계 구조가 바뀌면 `config/ci/**`라 [w2-fe-2 파일]이다.
|
||||
- 완료 기준: 유효한 증거면 FE-RB-005가 PASS다. releaseId가 다르거나 만료된 증거는 PASS가 아니다. 또는 (b)의 문서와 job 그래프.
|
||||
- RED: `tests/unit`에서 `drill-runbook.ts`의 판정 함수에 유효한 provider 증거를 넣으면 `PASS`여야 한다. 지금은 입력이 없어 `UNVERIFIED`라 실패한다.
|
||||
|
||||
### 3.25 0929/11-07 — 남음
|
||||
- 지금 등급: Low·P3.
|
||||
- 근거: `run`(`fixture-builds.ts:47`, `service-worker-builds.ts:169`)과 한 번 치환(`editOnce` `:35`, `replaceOnce` `:103`)이 두 벌이다.
|
||||
- 최소 개선: SW helper가 `prepareFixtureBuilds`를 쓰고, SW 선택·probe 치환만 `edit` 콜백으로 넘긴다.
|
||||
- 완료 기준: 빌드 준비 코드가 한 곳이다. 준비 실패 뒤 `/tmp`에 남는 것이 없다.
|
||||
- RED: `tests/unit`에서 `service-worker-builds.ts`가 `fixture-builds.ts`의 준비 함수를 import하는지(정적 검사), 그리고 준비 중 실패를 낸 fixture 뒤 임시 디렉터리가 비었는지 본다. 지금은 첫 단언이 실패한다.
|
||||
|
||||
### 3.26 1101/13-03 — 남음 [w2-fe-2 파일: 생성 workflow]
|
||||
- 지금 등급: Medium·P2. fail-closed라 틀린 것이 나가지는 않지만 운영 단계 자동화를 막는다.
|
||||
- 근거:
|
||||
- namespace 요구 주석은 gate의 `hostRequirements`에서 나오므로 merge_test에만 붙는다(`quality-gates.yml:80-81`).
|
||||
- provider job 둘(`:295`, `:341`)은 `runs-on: ubuntu-latest`이고 주석·점검이 없다. 시작 점검은 `/usr/bin/bwrap` 존재만 본다.
|
||||
- provider 없이 배포하는 절이 문서에 없다.
|
||||
- 최소 개선:
|
||||
- (1) 지금 할 수 있다. `config/ci/gates.json` jobs에 provider job의 `hostRequirements`를 두고 생성기가 주석을 쓴다. provider job 시작 때 `check-system-test-prerequisites.ts`의 namespace probe를 돈다.
|
||||
- (2) 소유자 결정이 필요하다. "provider 없이 배포할 때" 절(무엇을 배포하고 무엇이 빠지는가)을 쓴다.
|
||||
- 완료 기준: 문서만 보고 provider job runner를 만들 수 있다. provider 없는 프로젝트가 배포할 파일과 남는 위험을 문서에서 찾는다.
|
||||
- RED: `tests/unit/ci-workflow-generation.test.ts`에 단언을 더한다. 생성 workflow의 `vulnerability_provider` job 블록에 `runner requirement: unprivileged user and network namespaces` 주석이 있어야 한다. 지금은 없어 실패한다.
|
||||
|
||||
### 3.27 0929/13-02 — 남음
|
||||
- 지금 등급: Medium·P2. 문서가 권하는 입력 방식(`.env.example:14` "`.env.local`로 복사")에서 조용히 갈린다.
|
||||
- 근거: `vite.config.ts:19`는 `loadEnv`로 미선언 변수만 거절한다. base·설정 URL은 `process.env`를 읽는다(`:193-194`). build manifest·SW·runtime config 생성도 `process.env`다. 번들은 `.env.local`의 값을 `import.meta.env`로 받는다.
|
||||
- 최소 개선: `vite.config.ts`에서 `loadEnv(mode, cwd, "VITE_")`의 빌드 식별·경로 변수 셋이 `process.env`와 다르면 빌드를 멈춘다("이 변수는 셸로 준다"). `.env.example`에서 그 셋을 빼거나 "셸 전용"으로 적는다.
|
||||
- 완료 기준: `.env.local`에 `VITE_ROUTER_BASE_PATH=/app/`만 두고 빌드하면 빌드 단계에서 실패한다(실험 ⑥).
|
||||
- RED: `tests/unit/build-environment.test.ts` 같은 곳에 시험을 둔다. 임시 디렉터리의 `.env.local`에 값을 두고 `vite.config.ts`의 검사 함수를 부르면 던져야 한다. 지금은 함수가 없어 실패한다.
|
||||
|
||||
### 3.28 0929/13-03 — 남음
|
||||
- 지금 등급: Medium·P2. fail-closed다.
|
||||
- 근거: route chunk를 `entry.name === runtime?.moduleId && entry.isDynamicEntry`로 찾는다(`generate-build-manifest.ts:70-77`). 청크 이름이 선언 없이 계약이 된다. 메시지 `Missing built route chunk: <routeId>`는 이유를 말하지 않는다.
|
||||
- 최소 개선: manifest의 소스 경로(키 또는 `src`)로 route 청크를 찾는다. 안 되면 메시지에 "청크 이름이 route runtime의 `moduleId`와 같아야 한다(`vite.config.ts` 청크 이름 규칙)"를 적는다.
|
||||
- 완료 기준: 청크 이름을 바꾸는 변경(실험 ②)에서 빌드가 통과한다. 해시 안정성 테스트가 이름 가정 없이 실패해야 할 때(실험 ③)만 실패한다.
|
||||
- RED: route runtime 청크의 `name`이 다른 fixture manifest로 route 청크 찾기 함수를 부른다. 소스 경로로 찾아야 한다. 지금은 throw라 실패한다. 함수를 떼야 한다.
|
||||
|
||||
### 3.29 0929/13-04 — 남음
|
||||
- 지금 등급: Low·P2.
|
||||
- 근거: 같은 CSP가 선언 1곳 + fixture 4곳이다. `check:browser-security`에 내용 검사가 없다. 문서 사본은 사라졌다.
|
||||
- 최소 개선: `check-browser-security.ts`가 `security-headers.json`의 CSP에서 `'unsafe-inline'`, `'unsafe-eval'`, `*`, `script-src`의 scheme-only 값을 거절한다. fixture는 선언 파일을 읽어 만든다.
|
||||
- 완료 기준: 선언에 `'unsafe-inline'`을 넣으면 `check:browser-security`가 실패한다. CSP를 바꿀 때 한 파일만 고친다.
|
||||
- RED: 단위 시험 둘. CSP 검사 함수에 `script-src 'self' 'unsafe-inline'`을 넣으면 실패 줄이 나와야 한다. `tests/fixtures/hosting/response-headers.json`의 CSP가 선언과 같아야 한다(복사 대신 생성으로 바꾸기 전 임시 고정). 지금 첫째는 함수가 없어 실패한다.
|
||||
|
||||
### 3.30 0929/13-05 — 남음
|
||||
- 지금 등급: Low·P2.
|
||||
- 근거: `scheduler@0.27.0`이 `scope: development`다(`dependency-baseline.json:5778-5781`). 실제로는 react-dom 청크에 실린다. `supply-chain.ts`가 `pnpm list`의 `deduped` 노드를 따라가지 않는다.
|
||||
- 최소 개선: 비-deduped 노드로 `name@version → 자식` 표를 만들고 production 루트부터 폐포를 계산한다. 기준선을 다시 승인한다.
|
||||
- 완료 기준: SBOM·기준선에서 `scheduler@0.27.0`이 production이다.
|
||||
- RED: `tests/unit/supply-chain.test.ts`에 시험을 둔다. `deduped: true` 자식을 가진 fixture `pnpm list` 트리를 넣으면 그 패키지가 production이어야 한다. 지금은 development라 실패한다.
|
||||
|
||||
### 3.31 0929/13-06 — 일부
|
||||
- 지금 등급: Low·P3. 하위 경로 배포에서만 닿는다.
|
||||
- 근거: `hosting-probe.ts:470-473`이 `HOSTING_BASE_URL`의 path가 `/`가 아니면 거절한다. SW 쪽 소비자는 고쳐졌다.
|
||||
- 최소 개선: probe가 `HOSTING_BASE_URL` 기준 상대 경로(`config.json`, `release-manifest.json`)로 요청한다. 루트 강제는 빼거나 `VITE_ROUTER_BASE_PATH`와 같은지만 본다.
|
||||
- 완료 기준: `/app/` 빌드에서 probe가 `/app/` 아래 경로를 요청하고 통과한다.
|
||||
- RED: `tests/unit/hosting-probe.test.ts`에 `https://example.test/app/` 기준 가짜 fetcher를 둔다. 요청 URL이 `/app/config.json`이어야 한다. 지금은 루트 강제로 실패한다.
|
||||
|
||||
### 3.32 0929/13-10 — 남음
|
||||
- 지금 등급: Low·P3.
|
||||
- 근거: `README.md:281`은 "바꾸지 않은 `.template-origin` 커밋 checkout에서 재현되면 템플릿 결함"만 적는다. 문서화된 선택 기능·설정을 켜야 재현되는 경우의 책임이 비어 있다.
|
||||
- 최소 개선: "수정하지 않은 checkout에서 **문서화된 선택 기능·설정만 바꿔** 재현되면 템플릿 결함이다" 한 줄을 더한다.
|
||||
- 완료 기준: README 규칙이 선택 기능 재현을 적는다.
|
||||
- RED: 해당 없음(문서).
|
||||
|
||||
### 3.33 R-2 — 남음(제안)
|
||||
- 지금 등급: Low·P3.
|
||||
- 근거: 빌드 ID·release ID 기본값을 일곱 곳에서 따로 계산한다(표 근거). `||`와 `??`가 섞인다. 그래서 `VITE_BUILD_ID=""`이면 runtime config는 `local-build`가 되고, build manifest·SW·재현 빌드 기록은 `""`가 된다(코드 읽기, 미실행).
|
||||
- 최소 개선: `scripts/lib/build-environment.ts`에 `readBuildInputs(env)` 하나를 두고 모든 소비자가 그것을 쓴다. 빈 문자열은 한 규칙(없음과 같음, 또는 거절)으로 처리한다.
|
||||
- 완료 기준: `git grep '"local-build"'`이 정의 한 곳과 테스트만 찾는다. `VITE_BUILD_ID=""` 빌드의 네 산출물이 같은 값을 갖는다.
|
||||
- RED: 단위 시험 하나. `readBuildInputs({ VITE_BUILD_ID: "" })`의 결과를 runtime config 생성·manifest 생성에 넘긴 값이 같아야 한다. 지금은 함수가 없어 실패한다. 정적 단언(`local-build` 리터럴 위치 수 = 1)도 지금 실패한다.
|
||||
|
||||
### 3.34 1106/12-02 — 고쳐짐(게이트 단위), 남은 것
|
||||
- 지금 등급(남은 것): Low·P3. 검사가 거짓 PASS를 낸다. 다만 문서가 금한 사용이고 게이트는 막는다.
|
||||
- 근거: 아래 넷은 루트를 읽고 스스로 거절하지 않는다.
|
||||
- `check-app-build-input.ts:88`(`artifacts/quality/vite-module-inventory.json`)
|
||||
- `check-optional-recipes.ts:38`(`dist`)
|
||||
- `lib/release-candidate.ts:104`(`dist`)
|
||||
- `verify-reproducible-build.ts:25`(`dist` digest, 빌드는 `process.env`로 돈다)
|
||||
|
||||
게이트 안에서는 FE-GATE-012의 `check:bundle`, FE-GATE-013의 `build:release-candidate` 안 `generate:supply-chain`이 같은 변수로 거절해 게이트는 실패한다. 단독 실행은 막지 못한다. `RUN_OUTPUT_ROOT=.tmp/x corepack pnpm verify:reproducible-build`는 이전 루트 `dist`를 두 번 재서 `passed: true`를 쓸 수 있다(E1).
|
||||
- 최소 개선: 넷의 시작에 `checkoutBuildReadFailure(<script>)`를 부른다(`check-bundle.ts:29-33`과 같다).
|
||||
- 완료 기준: `RUN_OUTPUT_ROOT=.tmp/x`로 넷을 각각 돌리면 변수 이름을 적고 rc=1이다.
|
||||
- RED: `tests/unit/run-isolation.test.ts`에 시험을 둔다. 네 스크립트 소스가 `checkoutBuildReadFailure`를 부르는지(정적), 또는 `RUN_OUTPUT_ROOT=.tmp/x`로 `node scripts/check-optional-recipes.ts --require-dist`를 띄우면 rc=1인지 본다. 지금은 통과(또는 다른 이유)라 실패한다.
|
||||
|
||||
### 3.35 1106/14-02 — 재발
|
||||
- 지금 등급: Low·P3(원래와 같다).
|
||||
- 근거:
|
||||
- `121e1125`(nginx 정리)·`429b8d88`·`0805910c` 본문이 "이 커밋 30a379f 트리"·"네 커밋의 끝 30a379f"를 적는다.
|
||||
- `9c87cc4d` 본문이 "샘플을 지운 트리(8c4b09b7)"를 적는다.
|
||||
- `30a379fa`·`8c4b09b7`은 이 노트북에만 있는 다시 짓기 전 객체다. `git branch -a --contains` 0개다. 트리가 각각 `121e1125`·`e3c8db48`과 같다.
|
||||
- 새 clone에서는 열리지 않는다.
|
||||
- CHANGELOG 머리(`CHANGELOG.md:12`)의 대조 단계는 "그 라운드 리뷰 README의 조치 절"에 결과를 적게 해서 리뷰 라운드 통합에만 묶였다. 정리 PR #11·#12의 통합은 대조 기록이 없다.
|
||||
- 이력은 고치지 않는다(1106 결정 14-02). 해시 대조 도구도 더하지 않기로 했다.
|
||||
- 최소 개선(결정 안에서):
|
||||
- 대조 단계를 리뷰 라운드가 아니라 "해시를 다시 쓴 모든 통합"의 단계로 옮긴다. 위치는 `docs/work/improve.md`의 병합 단계 또는 `docs/work/delegate.md`의 통합 절차이고, PR 본문 「검증」 칸에 결과를 적는다.
|
||||
- 이번 두 해시의 대응(`30a379f` → `121e1125`, `8c4b09b7` → `e3c8db48`)을 CHANGELOG 정리 단계 절 머리나 다음 리뷰 README에 적는다.
|
||||
- 완료 기준: 다음 hash 재작성 통합의 PR 본문(또는 기록)에 대조 결과가 있다. 두 대응이 repo 안 문서에 있다.
|
||||
- RED: 해당 없음. 도구를 두지 않기로 한 결정이 있다. 문서 시험으로는 `docs/work/improve.md`에 `merge-base --is-ancestor` 단계가 있는지 볼 수 있다.
|
||||
|
||||
### 3.36 1106/15-01 — 일부 · 결정 재검토(D9, 새 증거)
|
||||
- 지금 등급: Low·P3.
|
||||
- 근거:
|
||||
- D9 규칙은 "예산 = 드릴 + 1 KiB를 KiB 단위로 올림"이고, 되돌림은 "다시 볼 때마다 드릴을 재고 204,800 B 이하이면 내린다"이다(`performance-evidence.md:54-62`).
|
||||
- "다시 볼 때"는 "예산을 또 넘을 때 / 1103/13-03 결정 때" 둘뿐이다(`:50-53`).
|
||||
- 예제를 지운 뒤 템플릿은 194,403 B다(FE-GATE-012, 이번 실행).
|
||||
- 기록으로 계산한 드릴은 194,403 + 6,327 + 약 543 ≈ 201,273 B다(추론, FE-GATE-020 값 미확인). 규칙대로면 202,297 → 198 KiB = 202,752 B다.
|
||||
- 지금 206,848 B는 규칙보다 4 KiB 크다. 템플릿 여유는 12,445 B다.
|
||||
- 문서의 "드릴 위의 여유 1,383 B … 이 규칙에 템플릿 자신이 더 쓸 몫은 없다"(`:57-59`)는 지금 상태가 아니다.
|
||||
- 1106/15-01이 남긴 위험("예산 값을 규칙 밖으로 두어도 실패하는 시험이 없다")이 기준선 감소로 실제가 됐다.
|
||||
- 고칠 수 없는 이유: 예산 값과 재검토 조건은 D9(메인 세션·사용자) 결정이다. 다만 `decisions.md:16`(1절 4)가 "전제가 틀렸다는 새 증거"로 다시 열 수 있게 한다. 이 행은 그 증거다.
|
||||
- 최소 개선:
|
||||
- (1) 드릴 값을 FE-GATE-020으로 재고, D9 규칙대로 `initialJsGzipBytes`를 내린다. 낮추는 쪽이라 게이트를 약하게 하지 않는다.
|
||||
- (2) "다시 볼 때"에 "기록 `gzipBytes`가 1 KiB 넘게 줄 때"를 더한다.
|
||||
- (3) `tests/unit/feature-shape-growth.test.ts`가 `budgets.json` 값이 `ceil((기록 + firstFeature + perFeature + perContext + 1024) / 1024) × 1024` 이상, 그것 + 1 KiB 미만인지 본다.
|
||||
- 같은 모양의 `initialJsFiles` 32(규칙 "템플릿 수 + 6", 지금 17)는 3절 PB-N2에 적었다.
|
||||
- 완료 기준: 예산이 규칙 값과 같다. 규칙 밖 값으로 바꾸는 변이에서 `test:unit`이 실패한다.
|
||||
- RED: 위 (3) 시험. 지금 206,848은 범위(202,752 이상 203,776 미만)를 넘어 실패한다.
|
||||
|
||||
## 4. 넘길 것 (새 발견 후보, 이 행들의 판정 중 본 것)
|
||||
|
||||
- **PB-N1(Low·P3, 일관성 23·소유 26).** `docs/work/reference/decisions.md` 3.1절이 1106의 결정 대기 22건 중 D1·D2·D3·D11·D6(1105)만 적는다. 이 리뷰 행 중 8건(1105/15-04 두 묶음, 1103/14-02, 1103/16-06, 0929/14-06, 1101/10-05·10-06·10-08, 0929/12-07)이 빠졌다.
|
||||
- 이미 난 결정도 2.2절 색인에 없다. CI 계약 기준선 삭제·FE-GATE-029 main 단계(2026-11-07, `f6b2b96c`), 문서 체계 적용(2026-11-08, PR #15), 샘플 삭제(2026-11-07, `e3c8db48`)다.
|
||||
- 같은 문서 `:64`가 "이 형식을 채우지 못하면 결정 대기가 아니라 미완"이라고 적는다.
|
||||
- 방향: 빠진 결정 대기를 3절 형식으로 올리거나 고친다. 난 결정 셋을 2.2절에 색인한다.
|
||||
- RED: 문서 시험 하나. 최신 리뷰 README가 "결정 대기"로 센 ID가 모두 `decisions.md` 3.1에 있어야 한다.
|
||||
- **PB-N2(Low·P3, 13·21).** `config/performance/budgets.json:5` `initialJsFiles` 32는 "정할 때 템플릿 그대로의 수에 6칸"이다(`performance-evidence.md:217-219`). 템플릿이 17파일이 된 뒤 15칸이다. D9와 같은 모양(기준선이 줄어도 상한이 그대로)이라 같은 재검토가 필요하다. 1103/15-05 소관이다.
|
||||
- **PB-N3(Low·P3).** 1103/16-06 덧붙임: `docs/manual/01-add-a-feature.md:432`의 "(플랫폼 라우트만)"이 코드와 다르다(3절 1103/16-06 상세).
|
||||
- **PB-N4(Low·P3).** 1106/12-02 남은 것: 스크립트 넷이 `RUN_OUTPUT_ROOT`에서 스스로 거절하지 않는다(3절 1106/12-02 상세). 새 ID로 셀지 1106/12-02의 남은 것으로 둘지는 총괄이 정한다.
|
||||
|
||||
## 5. 실험 요청
|
||||
|
||||
모두 desktop, `scripts/verify.sh exec -- …` 꼴이다. 실험마다 작업 폴더를 되돌린다.
|
||||
|
||||
| ID | 무엇을 | 명령 | env | 상한 | 기대 |
|
||||
|---|---|---|---|---|---|
|
||||
| PB-X1 | 1106/15-01·1103/13-03 드릴 값, 1101/10-06 횟수 | 실행 없음. 진행 중인 r9fe-base FE-GATE-020이 끝나면 `gate-artifacts/FE-GATE-020.txt`에서 `initial JS`, `sample removal: SKIP`, `test:unit`/`test:all` 실행 줄 수를 읽는다 | — | — | 드릴 약 201.3 KB, unit 약 9번 |
|
||||
| PB-X2 | 1105/16-04 거짓 양성 | `scripts/verify.sh exec -- bash -c 'corepack pnpm create:feature product-feature && corepack pnpm test:sample-removal -- --feature=product-feature'` | `CI=true` | 40분 | rc=1, `fixture-id-residue`에 `src` 10파일 이상 |
|
||||
| PB-X3 | 1106/12-02 남은 것 | `scripts/verify.sh exec -- bash -c 'corepack pnpm build && RUN_OUTPUT_ROOT=.tmp/pb-x3 corepack pnpm verify:reproducible-build; echo rc=$?; cat artifacts/release/reproducible-build.json'` | local env | 15분 | rc=0, `passed: true`(거짓 PASS) |
|
||||
| PB-X4 | 1101/12-03 probe | 아래 패치 적용 뒤 `scripts/verify.sh exec -- corepack pnpm check:design-system` | — | 5분 | rc=0(probe를 못 잡음) |
|
||||
| PB-X5 | 0929/12-03 두 단계 길 | `create:feature probe-feature` 뒤 아래 PB-X5 패치, `scripts/verify.sh exec -- corepack pnpm check:architecture` | — | 15분 | rc=0(길을 못 막음) |
|
||||
|
||||
PB-X4 패치(새 파일 둘):
|
||||
|
||||
```diff
|
||||
--- /dev/null
|
||||
+++ b/src/presentation/styles/theme/pb-x4-probe.css
|
||||
@@ -0,0 +1,4 @@
|
||||
+.pb-x4-a { background: linear-gradient(in oklch, var(--color-action), white); }
|
||||
+.pb-x4-b:focus-visible { outline-offset: 0; }
|
||||
+:root { --font-sans: serif; }
|
||||
+.pb-x4-c { color: color-mix(in OKLCH, red, blue); }
|
||||
--- /dev/null
|
||||
+++ b/src/features/pb-x4/probe.css
|
||||
@@ -0,0 +1 @@
|
||||
+.pb-x4-d { color: #ff0000; background: color-mix(in oklch, red, blue); }
|
||||
```
|
||||
|
||||
기대: `pb-x4-c`(B1)만 실패 줄이 나오고 나머지는 통과한다. 만약 rc=1이면 B1 줄 하나뿐인지 본다.
|
||||
|
||||
PB-X5 패치(`probe-feature` 생성 뒤, 생성 파일 이름은 실행 결과에 맞춘다):
|
||||
|
||||
```diff
|
||||
--- /dev/null
|
||||
+++ b/src/features/probe-feature/support/gateway-reexport.ts
|
||||
@@ -0,0 +1 @@
|
||||
+export * from "../adapters/probe-http-gateway.ts";
|
||||
--- /dev/null
|
||||
+++ b/src/features/probe-feature/presentation/pb-x5-probe.ts
|
||||
@@ -0,0 +1 @@
|
||||
+export * from "../support/gateway-reexport.ts";
|
||||
```
|
||||
|
||||
## 6. 결함 아님 · 다시 열지 않은 것 (한 줄씩)
|
||||
|
||||
- 1105/12-03: README가 merge 목록을 `gates.json`에서 읽는다. CLAUDE.md는 가져오기뿐이다.
|
||||
- 1105/14-01·0929/12-04: 대상 코드가 지워졌다(예제 기능, CI 기준선). 소유자 결정이다.
|
||||
- 1103/12-05: 완료 기준 D1·D2가 성립한다. 지운 심볼 검사는 1103이 버린 대안이다.
|
||||
- 1101/14-07: 문서 위치가 수명을 정하고 기록은 머리 블록 상태 검사를 받는다.
|
||||
- 0929/11-05: 기준선 커밋이 기록에 있다. 그 뒤 코드 변경은 주석과 경로 문자열뿐이다.
|
||||
- README `:201`의 "Actions가 꺼져 있을 수 있다": 제품 복사본을 위한 조건문이라 지금 runner와 모순이 아니다.
|
||||
- FE-GATE-013의 desktop 실패: D8(2026-11-12)로 merge 판정에서 뺀다. 다시 올리지 않는다.
|
||||
- 1106/16-01의 한 단어 ID 미탐: 매뉴얼 "못 잡음"(`01-add-a-feature.md:793`)에 적혀 있어 완료 기준의 둘째 길이 성립한다.
|
||||
|
||||
## 7. 고칠 대상 (결정 대기 아님, 29건)
|
||||
|
||||
등급 · 한 줄 · 위치. `[w2]`는 w2-fe-2가 바꾸는 파일에 걸린다.
|
||||
|
||||
1. 0929/12-01 · Medium·P2 · fanout 실패 줄에 두 탈출 방법이 없다. 커서 허용 fixture·억제 수가 없다 · `scripts/check-request-fanout.ts:172-179`
|
||||
2. 0929/11-02 · Medium·P2 · provider 확인 drill이 어떤 입력으로도 PASS가 못 된다 · `scripts/drill-runbook.ts:523-527`, `:554` (택일 (b)는 [w2])
|
||||
3. 0929/11-04 · Medium·P2 · lab 판정이 부하로 뒤집힌다. 부하 기준 UNVERIFIED 없음 · `scripts/test-performance.ts:244-300`
|
||||
4. 1101/13-03 · Medium·P2 · provider job에 namespace 요구 주석·점검이 없다 · `.gitea/workflows/quality-gates.yml:295`, `:341` [w2]. provider 없는 배포 절은 소유자 결정
|
||||
5. 0929/13-02 · Medium·P2 · `.env.local`로 준 빌드 변수가 번들과 스크립트에서 갈린다 · `vite.config.ts:19`, `:193-194`, `.env.example:14`
|
||||
6. 0929/13-03 · Medium·P2 · route 청크를 청크 이름으로 찾고 이유 없이 멈춘다 · `scripts/generate-build-manifest.ts:70-77`
|
||||
7. 1105/15-04 (재발) · Low·P2 · lab이 기능 라우트를 하나도 재지 않는다(생성 라우트는 `session-required`) · `scripts/lib/lab-performance.ts:55-68`, `scripts/create-feature.ts:578`
|
||||
8. 0929/12-03 · Low·P2 · 계층 밖 폴더 → 자기 `adapters/` → `src/adapters` 두 단계 길 · `.dependency-cruiser.json:302-312`
|
||||
9. 0929/13-04 · Low·P2 · CSP 5벌, 내용 검사 없음 · `config/hosting/security-headers.json:4`, `tests/fixtures/hosting/response-headers.json:7`, `:17`, `:27`, `:42`
|
||||
10. 0929/13-05 · Low·P2 · SBOM이 `deduped`를 안 따라가 `scheduler`가 development · `config/security/dependency-baseline.json:5778-5781`
|
||||
11. 1105/12-01 ② · Low·P3 · provider 파일 대기 시간 초과에 stderr가 없다 · `tests/system/ci-runner/ci-artifact-contract.test.ts:1783`, `:1813` (시험 timeout 작업과 겹칠 수 있음)
|
||||
12. 1105/16-04 · Low·P3 · 제거 드릴 `src` 부분 문자열 거짓 양성(`product-feature` 10파일) · `scripts/lib/feature-residue.ts:61`, `:76-79` [w2 호출자]
|
||||
13. 1101/10-07 · Low·P3 · RPC 테스트 셋이 실제 1 s를 잔다 · `tests/unit/browser-rpc/browser-rpc-remediation.test.ts:389`, `:412`, `:588`
|
||||
14. 1101/15-04 · Low·P3 · setup이 DOM 없는 unit에도 RTL을 싣는다 · `tests/setup.ts:1`, `:4` [w2]
|
||||
15. 0929/14-02 · Low·P3 · 기준점 형식 둘, 옮기는 시점 문장 둘이 어긋난다 · `README.md:277`, `:279`
|
||||
16. 0929/14-03 · Low·P3 · README가 제품 소유·고치지 않는 파일 정본(매뉴얼 03 C·D)을 가리키지 않는다 · `README.md:254-281`
|
||||
17. 1101/12-03 · Low·P3 · 디자인 규칙 B2·B3·B7·B8·B9·B14 미탐 · `scripts/check-design-system.ts:24-26`, `:44-48`, `:146`
|
||||
18. 0929/13-06 · Low·P3 · live probe가 하위 경로 URL을 거절한다 · `scripts/lib/hosting-probe.ts:470-473`
|
||||
19. 0929/12-05 · Low·P3 · 실행 안 하는 `dependency-cruiser` 의존성 · `package.json:157` [w2]
|
||||
20. 0929/12-06 · Low·P3 · Vitest 폴더의 `*.spec.ts`를 게이트 안으로 센다 · `scripts/lib/ungated-tests.ts:18`, `:94-95` [w2 판정 결과 파일]
|
||||
21. 1101/15-03 · Low·P3 · CSS·라우트 lazy 합 예산 없음 · `scripts/check-bundle.ts:49-56` (예산 값은 소유자 결정, 기록은 지금)
|
||||
22. 1101/16-05 · Low·P3 · 경계 두 벌, `TelemetryPort` 두 타입, 소비자 없는 폐기 재수출 · `src/application/result.ts:9`, `src/presentation/routes/app-router.tsx:421`, `:625`
|
||||
23. 1101/16-06 · Low·P3 · 생성기가 뷰 mapper·문구를 기능 `contracts/`에 쓴다 · `scripts/create-feature.ts:340`, `:346`
|
||||
24. 0929/11-07 · Low·P3 · e2e 빌드 helper 두 벌 · `tests/e2e/support/fixture-builds.ts:35`, `:47`, `tests/e2e/support/service-worker-builds.ts:103`, `:169`
|
||||
25. 0929/13-10 · Low·P3 · 선택 기능을 켜야 재현되는 결함의 책임이 README에 없다 · `README.md:281`
|
||||
26. R-2 · Low·P3 · 빌드 ID 기본값 일곱 곳, `||`/`??` 섞임 · `src/contracts/env.ts:204`, `scripts/generate-runtime-config.ts:75-76` 외
|
||||
27. 1106/14-02 (재발) · Low·P3 · 정리 통합 커밋 본문이 닿지 않는 해시를 가리킨다. 대조 단계가 리뷰 라운드에만 묶였다 · `CHANGELOG.md:12`, 커밋 `121e1125`·`429b8d88`·`0805910c`·`9c87cc4d`
|
||||
28. 1103/16-06 문장 · Low·P3 · 매뉴얼이 lab은 플랫폼 라우트만 읽는다고 틀리게 적는다(칸 정리는 결정 대기) · `docs/manual/01-add-a-feature.md:432`
|
||||
29. 1106/12-02 남은 것 · Low·P3 · 스크립트 넷이 `RUN_OUTPUT_ROOT`에서 스스로 거절하지 않는다(`verify:reproducible-build` 단독 거짓 PASS) · `scripts/verify-reproducible-build.ts:25`, `scripts/check-optional-recipes.ts:38`, `scripts/check-app-build-input.ts:88`, `scripts/lib/release-candidate.ts:104`
|
||||
|
||||
고칠 대상은 아니지만 결정이 걸린 것:
|
||||
- 1106/15-01은 결정 재검토(D9, 새 증거)다. 예산이 규칙보다 4 KiB 크다.
|
||||
- PB-N1(결정 색인 빈틈)은 문서 수정이다. 결정 대기 8건을 미완에서 꺼내는 일이다.
|
||||
@@ -0,0 +1,45 @@
|
||||
# round9 반박 검증 V1 — L1 react · L9 adapters · L7 security
|
||||
|
||||
> round9 리뷰(2026-11-12, 대상 main `5250ff95`)의 영역 기록이다. 서브에이전트가 쓴 원문을 그대로 옮겼다. 바꾼 것은 이 인용 블록과, 작업 폴더 절대 경로를 `(작업 폴더)`로 줄인 것뿐이다. 발견 ID는 이 파일의 이름표(R-01 등)이고, 라운드 ID(`1112/NN-MM`)와의 대응은 [README](2026-11-round9-review.md) 15절이다.
|
||||
|
||||
|
||||
대상 `5250ff95`. 읽기만 했다. repo 파일을 고치지 않았고 노트북·desktop에서 아무것도 실행하지 않았다(증거 E1). L9의 2.5절 이월 항목은 뺐다.
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- 13건 판정: 확인 11, 확인·등급 조정 0, 반박 2(그중 1건은 제안으로만 남김), 실행 필요 0.
|
||||
- 반박: L9/R-03(문장이 repo 용어로 맞다), L9/C-01(코드 읽기로 네 지점 모두 bytes를 다시 만들지 않는다. 1106 05 영역 미검증 1행의 이월이다).
|
||||
- 근거 일부를 고친 것: L1/R-01의 "401 재전송 뒤 둘이 엇갈린다" 예는 템플릿 세션 자격 증명에서는 성립하지 않는다(아래 표). 등급은 그대로다.
|
||||
- 새 발견이 아닌 것: L1/R-02는 1106 README 16.8절 FR-03(남김)과 같은 결함이다. 이월로 한 번만 센다.
|
||||
- 등급을 바꾼 것은 없다. 다만 L1/R-02는 PA가 이월 판정에서 Medium·P2로 둔다. 같은 모양의 1106 DR-03이 Low·P3라서 Low·P3를 권한다. README 「심각도 조정」에 둘 중 하나를 적어야 한다.
|
||||
|
||||
## 1. 판정 표
|
||||
|
||||
| 원 ID | 판정 | 최종 등급 | 근거·반박 이유(file:line) | RED 위치 또는 실험 | 소유자 결정 필요?(이유) | 중복 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| L1/R-01 결과 불명 판정이 코디네이터·폼·생성 페이지 사본에 나뉨 | 확인(근거 일부 정정) | Medium·P2 (구조적 위험) | 성립: 코디네이터 `resendLeavesUnknown`(`src/presentation/adapters/query/application-query.ts:643-646`)과 폼 `resendLeftUnknown`(`src/presentation/forms/use-app-form.ts:522-530`)이 같은 판정을 따로 한다. 생성 페이지가 막기·안내·이동을 직접 한다(`scripts/create-feature-write-slice.ts:639-656`, `:674-680`, `:724-750`). repo 규칙 위반: `docs/work/reference/structure.md` 7절 "페이지마다 복사하지 않고 공용 폼 hook 안에서 한다(결함 패턴 C11)", `src/application/AGENTS.md:9`. C11의 사례가 1105/08-02·08-04이고, 이미 생성한 기능은 손으로 옮긴다(`CHANGELOG.md:196`). 정정: "401 재전송 뒤 코디네이터는 UNKNOWN을 쥐고 폼은 비운다"는 템플릿 세션에서는 틀리다. 401 → `authSession.onUnauthenticated()`(`src/bootstrap/runtime-adapters.ts:620`) → 같은 호출 안에서 scope FENCED(`src/adapters/query-cache/server-state-scope-runtime.ts:120-150`) → `mutationFn`이 `SCOPE_GENERATION_CHANGED`로 끝내고(`application-query.ts:463-476`) `resendLeavesUnknown`이 scope 검사로 false → admission 정리. 엇갈림은 fence하지 않는 제품 provider 401에서만 남는다 | RED: 생성 출력 정적 시험(`tests/unit/create-feature.test.ts`): 생성된 `<base>-create-page.tsx`에 `mutation.state.indicator` 비교·`useRef(false)` 마운트 표시가 있으면 실패. 고친 뒤 platform hook 시험은 `tests/component/form-foundation.test.tsx` | 예. 새 공용 hook을 design-system 배럴에 내보내고 생성 출력을 바꾼다(배럴 표면). 대안 A/B/C 고르기도 소유자 몫 | 관련: PA-01(지운 재마운트 시험), L1/R-02 |
|
||||
| L1/R-02 재마운트 폼 재전송이 보낸 적 없는 화면 값을 제출 값으로 씀 | 확인 | Low·P3 | `use-app-form.ts:425` `unknownSubmissionRef.current ?? values` → 성공이면 `applyOutcome` → `settleSuccessfulValues(화면 값)`(`:261-263`, `:218-229`). 결과 불명에 남으면 화면 값을 보관(`:430-435`) → 확인 때 `settleApplied`가 그 값을 지움(`:235`, `:248`). 같은 상황의 `settleApplied` 재마운트 분기는 값을 둔다(`:236-246`, `CHANGELOG.md:196`). 덧붙임: 생성 페이지는 재전송 성공 때 pending 중에 상세로 이동하고 그동안 이탈 확인이 꺼진다(`create-feature-write-slice.ts:680`, `:744`). hook만 고쳐서는 이 경로의 입력이 남지 않는다. 페이지 쪽 동작은 R-01과 같이 정한다 | RED: `tests/component/form-foundation.test.tsx`. 새 폼에 값을 입력하고 `resendUnknown(성공)` → 값·`dirty=true`가 남는지. 두 번째 경우: `resendUnknown`이 NOT_APPLIED 429로 남은 뒤 `settleApplied` → 값이 남는지. 실험 X-L1-01 | 아니오(폼 내부 동작) | **같은 결함: 1106 README 16.8 FR-03(남김), PA `1106/03-01 ① FR-03`**. 새 발견으로 세지 않는다. 등급: PA Medium·P2 대 L1 Low·P3. 같은 모양 DR-03이 Low·P3 |
|
||||
| L1/R-03 생성 입력이 scope fence로 끊긴 요청을 실패 telemetry로 보냄 | 확인 | Low·P3 | `scripts/create-feature.ts:941`은 `REQUEST_ABORTED`만 뺀다. fence는 `SCOPE_GENERATION_CHANGED`로 온다(`src/adapters/http/http-execution-v3.ts:720-732`, `src/adapters/http/feature-http-binding.ts:494-495`, `:557-558`). 근거가 더 있다: 플랫폼 자신의 HTTP telemetry는 `SCOPE_FENCE` 취소와 `SCOPE_FENCED` 위반을 실패로 세지 않는다(`src/bootstrap/runtime-adapters.ts:254-282`). 렌즈 기준 `.claude/skills/fe-react/SKILL.md:55` "abort를 … telemetry 실패로 세지 않는다" | RED: `scripts/create-feature.ts` `renderInputTest`(`:1271` 옆)에 `SCOPE_GENERATION_CHANGED` 경우를 더한다. 생성·실행은 FE-GATE-020 드릴이 한다. 실험 X-L1-02 | 아니오(`errors.ts`에 판정 함수 추가는 추가만) | 없음 |
|
||||
| L1/R-04 query·mutation 실패 진단이 원인을 버림 | 확인(영향 좁힘) | Low·P3 | (1) `src/adapters/query-cache/tanstack-query-cache.ts:24-44`가 모든 실패를 `cache.operation.failed` warn으로 남긴다. `ApplicationQueryError`에 `kind`가 없어(`application-query.ts:54-62`) `safeErrorKind`(`src/contracts/diagnostics.ts:241-266`)가 늘 `APPLICATION_QUERY_ERROR`를 낸다. 런북은 이 이벤트로 cache 장애 범위를 좁힌다(`docs/operations/client-cache-and-storage-recovery.md:66`). `structure.md` 7절 "서로 다른 실패를 같은 reason으로 남기지 않는다". (2) `operationId` 리터럴(`application-query.ts:175`, `:704`, `:761`) 그대로다. 좁힌 점: HTTP 요청의 원인은 `http.request.completed`에 `error_kind`로 남는다(`runtime-adapters.ts:204-237`, `eventId` `:218`). "원인을 버린다"는 cache 이벤트와 예상 밖 throw에만 맞다 | RED: `tests/unit/query-cache.test.ts`에 `createQueryClient` + diagnostics spy, `ApplicationQueryError` 모양 실패 mutation 뒤 기록 0건(또는 kind 실림). (2)는 `tests/component/application-query-bridge.test.tsx`에서 bound query의 예상 밖 throw 실패 `operationId`가 정의 ID인지. 실험 X-L1-03 | 아니오 | 없음 |
|
||||
| L1/R-05 stale 실패를 effect로 state에 복사, 다시 시도 초기화가 바로 덮임 | 확인 | Low·P3 | `application-query.ts:103`, `:185-196`. TanStack 5.101.4(`package.json:131`)는 data가 있으면 재조회 중에도 `status: "error"`를 둔다. `isFetching` 변화로 effect가 다시 돌아 `true`로 되돌린다. `deriveAsyncState`가 `stale-degraded`를 `refreshing`보다 먼저 고른다(`src/application/view-models/async-state.ts:118-129`). 렌즈 기준 `.claude/skills/fe-react/SKILL.md:37`, `:49`. 기존 시험은 다시 시도 중 표시를 보지 않는다(`tests/component/application-query-bridge.test.tsx:51-111`) | RED: `tests/component/application-query-bridge.test.tsx`. 실험 X-L1-04. 다시 시도 중 보일 상태는 fe-ux가 정한다 | 아니오 | 없음 |
|
||||
| L1/R-06 "모든 시도가 받는 거절" 판정이 `mapProblem`이 바꿀 수 있는 code를 읽음 | 확인 | Low·P3 (구조적 위험) | `src/contracts/errors.ts:273-279`가 `failure.code`·`httpStatus`를 본다. code는 기능 `mapProblem`이 먼저 정한다(`feature-http-binding.ts:339-341`, `:447-450`). repo 약속과 어긋남: 매뉴얼은 `mapProblem`이 code를 바꿀 수 있지만 "적용 여부는 못 바꾼다"고 적는다(`docs/manual/01-add-a-feature.md:390`). 그런데 code로 결과 불명 정리 여부가 바뀐다. 생성 템플릿은 code를 그대로 넘긴다(`create-feature-write-slice.ts:404-410`). 그래서 템플릿 경로에서는 닿지 않는다 | RED: `tests/integration/`에 실제 실행기 + 바인딩 + `useApplicationMutation`. KEYED Envelope create, `mapProblem`이 선언 code를 `VALIDATION_FAILED`로 바꾼다. 재전송 400 뒤 지금은 `indicator === null`, 고친 뒤 `mutation-effect-unknown` | 아니오(`AppFailure`에 선택 칸 추가는 추가만). 매뉴얼 01:390 문장도 함께 고친다 | 관련: 1106 FR-01(kind 쪽은 `b41990cd`가 고침. code 쪽이 남음) |
|
||||
| L9/R-01 매뉴얼 02 §7 업로드 예가 `declare module`로 capability를 보강 | 확인 | Low·P3 | `docs/manual/02-decision-tables.md:467`이 `declare module`로 보강한다. `docs/manual/03-outside-feature-folder.md:118-119`와 `recipes/frontend-capabilities/browser-file-session-capability.ts:24-31`은 이 방식을 막는다. node 프로그램은 `scripts/**`·`*.config.ts`만 넣어(`tsconfig.node.json`) `product-composition.ts`의 보강을 보지 못한다. 블록은 `f8005493`(2026-11-04), 규칙은 1105/02-03. 1105/02-03 수정이 놓친 사본이다 | 실험 X-L9-01. 상시 RED: §7 두 블록에 `manual-code-block` 표식을 달아 `tests/unit/manual-code-blocks.test.ts`가 타입 검사하게 한다(node 프로그램 포함) | 아니오(문서) | **같은 결함: L7 3절 넘김(ID 없음)**. 1105/02-03 「일부」로 셀 수도 있다 |
|
||||
| L9/R-02 지금 규칙인 표 둘이 설계서에만 있음 | 확인 | Low·P3 | poll 결과 대응표는 설계서 9.2절에만 있다(`docs/design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md:1698-1710`). 이 표대로 `execute`를 쓰는 쪽은 조합 코드다(`src/adapters/realtime/polling/bounded-poll-coordinator.ts:115-121`). 짝 백엔드 대응표는 같은 설계서 0.1절이고, 살아 있는 문서가 그 절을 출처로 가리킨다(`docs/architecture/optional-adapter-recipes.md:235-238`, `docs/manual/03-outside-feature-folder.md:125`). repo 규칙: `docs/README.md:70` "설계서와 기록은 … 지금 동작을 설명하지 않는다", `:115`·`.claude/rules/docs.md` 기록은 머리 블록만 고친다. 성격은 같은 모양인 L8/GD-17에 맞춰 확인된 결함으로 봐도 된다 | 정적 RED: `git grep -n "Design 9.2" -- src` 1건, `git grep -n "bounded-polling-design.md#01" -- docs/architecture docs/manual` 2건이 고친 뒤 0건. 문서 검사에 넣으려면 L2/S-06 RED와 함께 | 아니오(문서 이동) | 같은 원인·다른 문서: L8/GD-17, L2/S-06(2026-11-08 `99e76e87` 이동). 함께 고친다 |
|
||||
| L9/R-03 "현재 concrete runtime은 없다" 문장이 낡음 | **반박** | — | 이 repo 용어로 "concrete runtime"은 production bootstrap이 만들고 쓰는 runtime이다(`COMPOSED` 정의, `docs/design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md:64`, `docs/design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md:63`). 지금 조합은 realtime을 시작할 runtime이 없다. 고르면 조합을 거부한다(`src/features/installed-runtime-capabilities.ts:19-28`, `src/bootstrap/optional-runtime-host.ts:23`, `:110-111`). 그래서 문장은 catalog `AVAILABLE_NOT_COMPOSED`와 같은 말이다. 같은 절 다음 줄이 "이 repo의 SSE·`realtime.v1` WebSocket 어댑터"를 적어 참조 코드가 있음도 밝힌다(`optional-adapter-recipes.md:235-236`). 1101 리뷰도 이 문장을 "조합에 runtime 없음"의 근거로 썼다(`docs/reviews/2026-11-01-maturity-review/09-app-core.md:212`) | 제안으로만: "reference runtime은 있고 조합은 없다"로 풀어 쓰면 덜 헷갈린다 | 아니오 | 없음 |
|
||||
| L9/C-01 reconcile과 승인 partition 삭제의 겹침에 시험 없음 | **반박(제안으로만 남김)** | — | 지킬 약속(`docs/operations/browser-file-storage-recovery.md:490-491` "`partitionDeleted`면 bytes는 모두 지워졌다")을 네 지점 모두 코드가 지킨다. verify 전 삭제: manifest 없음 → `false`(`src/adapters/storage/opfs/opfs-worker-runtime.ts:701-712`) → staging이 partition 아래라(`:1669-1676`, `:870-881`) 이미 없음 → 없는 row의 rollback은 성공. verify 뒤 commit 전: `commitMutation`은 row가 없으면 `CONFLICT`로 끝나고 row를 만들지 않는다(`src/adapters/storage/opfs/indexeddb-opfs-journal.ts:997-1027`). commit 뒤 finalize 전: `finalizePut`이 `create: false`로 열고 NotFound면 staging 정리만 한다(`opfs-worker-runtime.ts:951-990`). finalize 뒤: 없는 row의 `complete`는 성공(`indexeddb-opfs-journal.ts:579-600`). 어디에도 `create: true` 경로가 없다. 시험 부재만으로는 약속 위반이 아니다. 1106 05 영역 5절 미검증 1행과 같은 항목이다(`docs/reviews/2026-11-06-maturity-review/05-adapters-storage-kernel.md:145`. 같은 문서 `:18`은 `commitPut` 앞·뒤 두 지점을 실행해 bytes가 남지 않았다고 적는다) | 선택: X-L9-02를 회귀 시험으로 올리면 E2가 된다 | 아니오 | 이월: 1106/05 미검증 1행 |
|
||||
| L7/SEC-01 업로드 401이 세션에 닿지 않음, JWT 모드 업로드 자격 증명 경로 없음 | 확인 | Medium·P2 | 업로드 client는 401을 `AUTH_REQUIRED` 실패로만 돌려준다(`src/adapters/http/fileserver-upload.ts:707-755`, 종류는 `envelopeFailureReading` → `src/contracts/errors.ts:320-321`). 알릴 hook이 없다(`:131-158`). 401을 세션·`onCredentialRejected`로 보내는 곳은 V3 경로뿐이다(`src/bootstrap/runtime-adapters.ts:605-623`, `:675-680`). 업로드 capability는 감싸지 않고 넘긴다(`:730-734`). 매뉴얼은 반대로 적는다: `docs/manual/02-decision-tables.md:492` "그 401은 세션을 로그아웃시킨다(5절)", 5절 `:354` "서버가 401을 주면 그 요청의 자격 증명을 낸 쪽만 안다". JWT 쪽: 짝 백엔드 기본은 `jwt`다(`docs/manual/04-paired-backend-session.md:16`). `ProductCompositionContext`에 세션 자격 증명이 없다(`src/bootstrap/product-composition-contract.ts:80-101`). §7 안내는 쿠키 프로필만 다룬다. 덜어 주는 것(등급 유지): `AUTH_REQUIRED`의 action이 `reauth`라 기능이 다시 로그인 버튼을 줄 수 있다(`src/contracts/errors.ts:69`). 다음 V3 401이 세션을 내린다. 그래서 P1이 아니다 | RED: `tests/unit/runtime-adapters-credential-order.test.ts` fixture에 제품 `fileserverUpload` capability + `onCredentialRejected` spy. MSW `POST /v1/files` 401 → spy 1회(지금 0회). 업로드 client 단위 동작은 `tests/integration/fileserver-upload.test.ts:367` 옆 | **예.** (a) 템플릿이 업로드 capability를 감싸거나 (b) `FileserverUploadClientDependencies`에 hook을 더한다(http 배럴 표면). JWT용으로 `ProductCompositionContext`에 함수를 더한다(제품 조합 계약) | 없음. 같은 블록의 `declare module`은 L9/R-01 |
|
||||
| L7/SEC-02 `minimumReleaseAgeExclude` 네 줄이 자기 재검토 조건을 넘김 | 확인 | Low·P3 | `pnpm-workspace.yaml:9-18`. 주석의 재검토 조건("older than the configured minimum release age")이 이미 찼다. 설정 키가 없어 pnpm 11 기본 1,440분이다(`tests/unit/pnpm-install-policy.test.ts:12`, `renovate.json:7`). 네 버전은 2026-07-25에 넣었다. 지워도 시험은 빈 목록을 받는다(`pnpm-install-policy.test.ts:28-36`) | 줄만 지우면 시험은 필요 없다. 규칙을 더하려면 `tests/unit/pnpm-install-policy.test.ts`에 "항목마다 지나지 않은 만료일" 단언(지금 실패) | 아니오(설정 정리. 게이트 기준을 낮추지 않음) | 없음 |
|
||||
| L7/SEC-03 secret scan·공급망 범위 설명이 실제보다 좁음 | 확인 | Low·P3 | 설명: `config/repository-layout.json:15`, `docs/security/supply-chain.md:24-25`. 코드: `git ls-files` 전부를 읽고(`scripts/lib/repository-file-inventory.ts:89-91`), `trackedRoots`는 비지 않았는지만 본다(`:262-273`). 정책에 `includedPaths`가 없어 전부 검사한다(`scripts/lib/secret-scan-policy.ts:34`, `scripts/lib/secret-scan-evaluator.ts:172-175`). 공급망 source 집합도 추적 파일 전부다(`scripts/generate-supply-chain.ts:202`). 코드 읽기로 충분해 EXP-L7-02는 필요 없다 | 지키는 시험: `evaluateSecretScan`에 `trackedRoots` 밖 추적 파일(`docs/x.md`)의 비밀값을 넣어 발견이 나는지 고정(지금도 통과) | 아니오(문서 문구. 검사 범위는 줄이지 않음) | 없음 |
|
||||
|
||||
## 2. 실험 목록
|
||||
|
||||
모두 확인을 E2로 올리는 실험이다. 판정을 가르는 데 꼭 필요한 실험은 없다. desktop에서 작업 폴더를 되돌리며 돈다. env 없음.
|
||||
|
||||
| ID | 대상 | 명령 | 패치 | 기대 결과 |
|
||||
|---|---|---|---|---|
|
||||
| X-L1-01 | L1/R-02 | `scripts/verify.sh exec -- node scripts/run-vitest.ts run tests/component/r9-l1-form-resend-remount.test.tsx` | `r1-L1-react.md` 4절 X-L1-01 그대로. `LocaleContext`에 기본값이 있어(`src/presentation/i18n/locale-provider.tsx:72`) provider 없이 돈다. 둘째 경우를 더한다: `resendUnknown(async () => ({ ok: false, error: createFailure("RATE_LIMITED", "X", 0, { effect: "NOT_APPLIED", httpStatus: 429 }) }))` 뒤 `settleApplied()` → 값 유지 | 지금 두 경우 모두 실패(값 `""`, `dirty=false`). 고친 뒤 통과 |
|
||||
| X-L1-02 | L1/R-03 | `r1-L1-react.md` X-L1-02 그대로 | 같은 곳 | 새 경우 1건 실패(emit 1회). 나머지 통과 |
|
||||
| X-L1-03 | L1/R-04 | `r1-L1-react.md` X-L1-03 그대로. `createQueryClient`는 배럴에 있다(`src/adapters/query-cache/index.ts:23`) | 같은 곳 | 지금 실패(기록 1건, `error_kind: APPLICATION_QUERY_ERROR`) |
|
||||
| X-L1-04 | L1/R-05 | `r1-L1-react.md` X-L1-04 그대로 | 같은 곳 | 지금 실패(다시 시도 중 `stale-degraded`) |
|
||||
| X-L9-01 | L9/R-01 | `r1-L9-adapters.md` X-L9-01 그대로 | 같은 곳(수정 담당이 만든다) | 그대로 적용: `check:types:node` 실패, rc≠0. 고친 안: rc=0 |
|
||||
| X-L9-02 | L9/C-01(선택) | `scripts/verify.sh exec -- node scripts/run-vitest.ts run tests/unit/opfs-worker-runtime.test.ts` | `r1-L9-adapters.md` X-L9-02(네 지점 hook) + 변이 `finalizePut`의 `getDirectory(…, false)` → `true` | 변이 없음: 네 지점 모두 통과(반박 근거가 E2가 된다). 변이: "commit 뒤 finalize 전"이 실패. 변이 없이 실패하면 반박을 거두고 C-01을 확인된 결함으로 다시 매긴다 |
|
||||
@@ -0,0 +1,63 @@
|
||||
# round9 반박 검증 V2 — L2(구조) S-01~S-10, L8(가드레일·문서) GD-01~GD-19
|
||||
|
||||
> round9 리뷰(2026-11-12, 대상 main `5250ff95`)의 영역 기록이다. 서브에이전트가 쓴 원문을 그대로 옮겼다. 바꾼 것은 이 인용 블록과, 작업 폴더 절대 경로를 `(작업 폴더)`로 줄인 것뿐이다. 발견 ID는 이 파일의 이름표(R-01 등)이고, 라운드 ID(`1112/NN-MM`)와의 대응은 [README](2026-11-round9-review.md) 15절이다.
|
||||
|
||||
|
||||
대상: 프론트 `5250ff95`(읽기만), 짝 백엔드 main `a7e38c10`(읽기만), w2-fe-2 PR #19 원격 브랜치 `claude/w2-fe-ci-perf-dce080`(FETCH_HEAD `ba72b865`, `git show`·`git diff`로 읽기만). 노트북·desktop에서 pnpm·node·python 시험을 돌리지 않았다. desktop은 `/tmp/claude-gates/r9fe-base/`의 로그만 읽었다. 증거는 따로 적지 않으면 E1이다.
|
||||
|
||||
## 0. 판정 건수
|
||||
|
||||
- 확인 21: S-02, S-03, S-04, S-06, S-07, S-08, S-10, GD-01, GD-06, GD-07, GD-08, GD-09, GD-10, GD-11, GD-13, GD-14, GD-15, GD-16, GD-17, GD-18, GD-19
|
||||
- 확인·등급 조정 6: S-01(P2→P3), S-05(P2→P3), GD-02(P2→**P1**), GD-03(P2→P3), GD-04(P2→P3), GD-05(P2→P3)
|
||||
- 반박 2(제안으로만 남김): S-09, GD-12
|
||||
- 실행 필요 0(실험은 증거를 E2로 올리는 용도다. 판정은 읽기로 가렸다)
|
||||
|
||||
## 1. 결과 표
|
||||
|
||||
| 원 ID | 판정 | 최종 등급 | 근거·반박 이유(file:line) | RED 위치 또는 실험 | 소유자 결정 필요?(이유) | 중복 |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| L2/S-01 | 확인·등급 조정 | Low·P3 (구조적 위험) | 성립: `scripts/check-architecture.ts:796-1039` assertion에 kernel 규칙이 없고, `tests/fixtures/architecture/dependency-graph/`에 adapter 간 fixture가 없다. `scripts/verify-documentation-readiness.ts:147-148`은 json→문서 방향만 본다. **반박(일부):** "그 줄이 바뀌어도 아무것도 실패하지 않는다"는 틀렸다. `scripts/tests/test_hooks.py:50`이 실제 `.dependency-cruiser.json`을 복사하고 `:108-115`가 http→auth import에 `adapters-do-not-know-other-concrete-adapters` 알림과 kernel 허용을 단언한다. X-02a(넓힘)·X-02b(삭제) 둘 다 이 시험을 깨뜨린다. 다만 이 시험은 노트북 `scripts/verify.sh hooks`(`scripts/verify.sh:88`)에서만 돌고 CI 게이트에는 없다(`config/ci/gates.json`·`.gitea/`에 unittest 없음). 규칙 변경은 크기 큼(`docs/work/README.md:25`)이라 소유자 검토를 거친다. 그래서 P3 | `check-architecture.ts` `runGraphFixtureChecks`에 `dependency-graph/kernel/` fixture와 assertion 둘(kernel 밖 거절, kernel 셋 허용). X-02a 패치에서 새 assertion이 실패해야 한다. 실험 X-V2-01 | 아니오(규칙은 그대로, fixture만 더함) | 없음 |
|
||||
| L2/S-02 | 확인 | Low·P3 (구조적 위험) | `.dependency-cruiser.json:338-348` routing 예외가 목적지 일곱을 모두 푼다. 실제 쓰임은 type import 둘(`src/platform/routing/context-route-module.ts:2-3`). `:140-149`는 `src/platform`을 다루지 않는다. presentation이 routing을 import한다(`src/presentation/routes/app-router.tsx:39`). `:302-312` contribution 예외는 모든 adapter edge를 푼다. 쓰는 것은 type 하나(`src/features/feature-adapter-contribution.ts:5-7`), 그래프는 type-only를 가리지 않는다(`scripts/check-architecture.ts:400-408`). presentation→contribution 파일을 막는 규칙도 없다(`:229-238`은 `installed-`만). ESLint도 platform·features 루트 패턴이 없다(`eslint.config.ts:13-38`). `layers.md:67`, `:70`이 "타입 전용", "타입으로 읽는"이라고 약속해 결함 성립 | `tests/fixtures/architecture/dependency-graph/cross-boundary/`에 `platform/routing/reexport.ts → adapters/telemetry/index.ts`와 contribution 파일의 value re-export를 더하고 거절 assertion(지금 실패). `tests/architecture/feature-adapter-reach.test.ts:50-53`도 같이 바꾼다. 실험 X-03 | 예(`.dependency-cruiser.json` 규칙·예외 변경은 크기 큼, `docs/work/README.md:25`. 좁히는 쪽이라 게이트를 약하게 하지 않는다) | 없음 |
|
||||
| L2/S-03 | 확인 | Low·P3 | (1) `src/presentation/pages/home-page.tsx:1-7`에 `installed-` import가 없다. `f849d781`이 `NAVIGATION_ROUTES` import를 `navigation-policy.ts`로 옮겼는데 `.dependency-cruiser.json:234` 목록은 그대로다. 규칙 comment(`:230`)가 "remove each file from the list"를 약속한다. (2) `src/presentation/templates/page-templates.tsx:5-8`이 index가 내보내는 `LinkButton`(`design-system/index.ts:17-21`)을 primitive에서 직접 가져온다. 예외 이유는 `PaginationLandmarkContext`뿐이다(`.dependency-cruiser.json:73`). (3) `layers.md:107-118` 목록에 contribution 예외가 없다(규칙 표 `:67`에는 있다). page-templates 예외는 "디자인 시스템 facade" 항목에 이름 없이 묶여 있어 (3)의 둘째는 약하다 | `check-architecture.ts`에 "`pathNot`에 이름 붙은 파일은 그 규칙 `to.path`에 맞는 edge를 하나 이상 가진다" 검사(지금 `home-page.tsx`에서 실패) | (1)만 예(규칙 목록 변경, 크기 큼). (2)(3)은 아니오 | 없음(L4/UX-06은 홈 화면 구성 문제로 다른 결함) |
|
||||
| L2/S-04 | 확인 | Low·P3 | `scripts/check-adapter-inventory.ts:216` 상한 13, 판정 `:230`(`>`). 다시 센 값 12. desktop 게이트 로그 `gate-artifacts/FE-GATE-010.txt:66` "hand-rolled abort wiring: 12/13 files (ratchet) PASS"(E2, CI env, 실제 runner 아님). `4d172590`(13으로 내림) 때 있던 `http/client.ts`(abort 리스너 3개)를 `048f490a`가 지웠다. `:212-213` 주석이 "숫자가 내려가면 이 상수도 같이 내린다"고 약속한다. `:135-139`의 "image-cdn-runtime·resumable-upload-runtime이 자기 사본을 들고 있다, 23개"는 두 파일이 kernel을 import하므로 틀렸다 | 판정을 `!==`로 바꾸거나 같음 단언(지금 12≠13으로 실패). 실험 X-04는 필요 없다(위 로그가 실측) | 아니오(스크립트 자신의 규칙이 내리라고 한다. 조이는 쪽) | 없음 |
|
||||
| L2/S-05 | 확인·등급 조정 | Low·P3 (작업 필요: pin 이동) | 사실은 맞다: pin `45d2a478`(`config/contracts/backend-contract-pin.json:5`), main까지 238커밋. 옛 경로 셋은 main에 없고 새 경로 내용은 pin과 같다(직접 비교). **빠진 것:** `scripts/new-feature.sh`도 바뀌었다(`git diff 45d2a478..a7e38c10` 19줄, 경로 문자열뿐이고 복수형 규칙은 그대로). 그래서 drift 실패는 넷이 아니라 다섯(문서 1 + scaffold 4)이다(`scripts/check-backend-contract-drift.ts:153-179`). **반박(일부):** 문서는 근거를 pin 기준이라고 명시한다(`docs/architecture/backend-api-and-server-state-contract.md:154`, `:270`). drift exit 1은 설계된 신호다(`:170-174` "1은 어긋남"). "절차가 막힌다"는 과장이다. pin을 main과 맞춰 둔다는 약속은 없다. 판정 자체는 main에서도 맞다(리뷰어 대조, `IdempotencyKeyHeader.java`는 main에 있음). 그래서 P3 | 실험 X-01(백엔드 main clone으로 drift, 지금 exit 1 → pin 이동 뒤 exit 0) | 예(pin은 짝 백엔드와 맞춘 계약 `config/contracts/`, 크기 큼 `docs/work/README.md:25`) | 관련: L8/GD-18(같은 pin 차이의 다른 문서). 실험 X-GD18과 합친다 |
|
||||
| L2/S-06 | 확인 | Low·P3 | `docs/architecture/backend-api-and-server-state-contract.md:3-8`, `docs/architecture/static-delivery.md:3-8`이 `docs/design/2026-07-30-…-closed-deep-design.md`를 "정본"이라 하고, 그 설계서 머리 블록 `:7`은 현재 정본을 `frontend-application-foundation.md`, `src/bootstrap/`로 적는다. `docs/README.md:70`, `docs/work/reference/structure.md:55`와 어긋난다. `99e76e87`(2026-11-08) 이동 때 남았다. 문서 검사에 이 판정이 없다(`scripts/lib/docs-system.ts:68`, `:76`은 폴더 분류만) | `scripts/lib/docs-system.ts`에 "살아 있는 문서가 `docs/design/` 링크를 정본이라 부르면 실패" 검사, `tests/unit/docs-system.test.ts`에 사례(지금 두 파일에서 실패) | 아니오 | 같은 원인(2026-11-08 설계서 이동): L9/R-02, L8/GD-17. 한 검사로 함께 막는다 |
|
||||
| L2/S-07 | 확인 | Low·P3 | (1) `src/contracts/AGENTS.md:3`, `docs/work/reference/structure.md:24`의 「Decision rule」 — 그 절은 「판단 규칙」(`docs/architecture/contract-ownership.md:6`). 절 이름 시험은 스킬만 본다(`scripts/tests/test_claude_setup.py:254-268`). (3) `structure.md:87` "pin과 drift는 문서 글자만 비교"는 틀렸다: 답 표 대조(`check-backend-contract-drift.ts:146-151`)와 scaffold 원본 diff(`:169-179`)가 있다. **(2)는 일부 반박:** `src/contracts/AGENTS.md:16`의 "(FE-GATE-007)"도 틀리지 않다. `tests/integration/fileserver-upload.test.ts:504-537`이 pin의 답 표를 읽어 FE-GATE-007에서 돈다. 주 대조 시험(`tests/unit/backend-contract-pin*.test.ts`)이 FE-GATE-005라는 것이 빠졌을 뿐이다 | `test_claude_setup.py:254`의 절 이름 시험을 루트·`src/*/AGENTS.md`, `docs/work/**/*.md`로 넓힌다(지금 「Decision rule」 두 곳에서 실패) | 아니오 | 없음 |
|
||||
| L2/S-08 | 확인 | Low·P3 | `docs/reviews/adapters/INVENTORY.md:7` "119개" vs 표 143행·`합계 143/143`(`:155`, `check-adapter-inventory.ts:66-75`가 검사). `:155` "상세 리뷰 inventory를 같은 변경에서 갱신"은 지켜지지 않았고(상세 리뷰 `01-network-and-state.md`는 2026-08-13 기록, 새 파일 행 없음) `.claude/rules/docs.md:9`(기록은 머리 블록만)와 부딪친다 | 없음(문장). 원하면 `check-adapter-inventory.ts`가 머리의 숫자를 거절 | 아니오 | 없음 |
|
||||
| L2/S-09 | 반박(제안으로만 남김) | — | 검사 다섯이 한 스크립트에 있다는 사실은 맞다(`scripts/check-adapter-inventory.ts:57-75`, `:77-95`, `:97-127`, `:129-187`, `:189-238`). 그러나 repo가 "스크립트 하나 = 검사 하나"를 약속한 곳이 없고, 각 검사는 실패 줄에 자기 이름(`adapter inventory:`, `service worker assets:`, `fixture node_modules:`, `abortable-operation:`)을 단다(`:51-52`, `:82`, `:110`, `:165`). 결함 아님. 옮긴다면 `tests/unit/fixture-node-modules.test.ts`는 [w2-fe-2 파일]이다 | — | 아니오 | 없음 |
|
||||
| L2/S-10 | 확인 | Low·P3 (구조적 위험, 사본이 아직 같음) | `src/bootstrap/runtime-adapters.ts:540-590`과 `:605-621`이 같은 순서를 따로 적는다(주석 `:600`이 동기화를 요구). `docs/work/reference/structure.md:62`(S1). **통제 정정:** 「미확인」이 아니라 M3(부분)이다. 두 함수를 함께 지나는 시험이 있다: `tests/unit/runtime-adapters-auth-profile.test.ts:371-446`(ANONYMOUS 401은 세션 유지, 세션 401은 로그아웃), `tests/unit/runtime-adapters-credential-order.test.ts:357-424`(제품 provider 401은 제품 hook만). 남은 빈틈은 "ANONYMOUS 프로필에 제품 provider가 등록된 401"처럼 순서만 다른 변이다 | `tests/unit/runtime-adapters-credential-order.test.ts`에 ANONYMOUS 프로필 id로 provider를 등록하고 401 → 제품 hook·세션 모두 불리지 않음 단언. 실험 X-V2-02(순서 바꾼 변이가 지금 살아남는지) | 아니오(템플릿 소유 bootstrap 안 정리, 공개 표면 그대로) | 관련: L7/SEC-01(업로드 경로에 같은 401 판정을 쓰려면 이 판정이 한 함수여야 한다) |
|
||||
| L8/GD-01 | 확인 | Medium·P2 [w2-fe-2 파일] | 지금 main: `scripts/verify.sh:58-65`가 `script`·`expect`·`expectedExitCode`만 내고, `:131-145`가 인자 없이 돌리고 `expect=fail`을 종료 코드로만 판정한다. `ci:gate`는 args를 넘기고(`scripts/run-ci-gate.ts:135-138`) 진단 문구까지 본다(`:153-176`, `scripts/lib/ci-step-result.ts:67`). FE-GATE-009의 `check-a11y-manual-format`은 `args: ["--","--format-only"]`이고 인자 없이는 서명 검토를 돌린다(`scripts/verify-a11y-manual.ts:24-39`, 기록 셋 모두 `pending-manual-review`). `.claude/skills/fe-design-system/SKILL.md:76`이 바로 `parts FE-GATE-029`를 쓰라고 한다. **PR #19:** `79a225b6`이 args 절반을 고쳤다(FETCH_HEAD `scripts/verify.sh` `\x1e` args, 시험 `test_parts_passes_each_command_its_arguments_as_ci_gate_does`). 진단 문구 절반은 PR에도 없다. PR 병합 뒤 남는 것은 FE-GATE-029 음성 fixture 거짓 PASS 하나(Low·P2) | `scripts/tests/test_verify.py`: PATH 앞 가짜 `corepack`이 exit 1과 엉뚱한 문구를 낼 때 `parts FE-GATE-029`가 rc=1인지(지금도 PR #19 뒤에도 실패). 실험 X-GD01b | 아니오(w2-fe-2 세션과 맞춤) | 없음 |
|
||||
| L8/GD-02 | 확인·등급 조정 | **Medium·P1** | `tests/unit/manual-code-blocks.test.ts:24`, `:56-69`, `:98-100`이 `REMOVAL_FIXTURE_COPY_TARGETS`(src 포함) 사본에 `invoice-feature`를 만든다. `scripts/lib/generated-feature.ts:23`, `:52-55`, `:96-110`과 `tests/e2e/boot-module-failure.spec.ts:32`가 사본에 `order-feature`를 만든다. 생성기는 같은 ID·같은 base를 거절한다(`scripts/create-feature.ts:215-225`, base는 `:136-140`). 매뉴얼은 1단계 명령으로 `create:feature invoice-feature`를 준다(`docs/manual/01-add-a-feature.md:97`). 경고는 AI playbook 한 줄뿐이고(`docs/work/new-feature.md:59`) `order-feature`는 그마저 없다. **등급 상향 이유:** `review-criteria.md` 3절이 "생성 명령으로 빠른 출시 약속을 깨는 것"을 Medium·P1로 둔다. 지원 구성(생성 명령으로 기능 추가)에서 merge 게이트 FE-GATE-005·008이 기능 코드와 무관하게 막힌다(P1 기준 "merge 단계 게이트를 막는 것"). 피하려면 템플릿 시험을 고쳐야 한다. **발생 조건 정정:** base가 정확히 `invoice`·`order`인 ID(`invoice`, `invoice-feature`, `order`, `order-feature`)다. `invoices-feature`(base `invoices`)는 걸리지 않는다 | `tests/unit/manual-code-blocks.test.ts`·`generated-feature.ts`의 사본 준비에 "같은 ID 기능이 이미 설치된 저장소"를 주는 단위 시험(지금 생성 단계에서 실패). 실험 X-GD02, X-GD02b로 E2 확인 권장(P1이라 종료 조건에 닿는다) | 아니오(템플릿 시험의 ID만 바꾸면 된다). 생성기에 예약 접두어 거절을 더하면 생성 명령 동작 변경이라 크기 큼 | 없음 |
|
||||
| L8/GD-03 | 확인·등급 조정 | Low·P3 | 성립: 점검은 system manager(`scripts/check-system-test-prerequisites.ts:83-88` `systemctl show-environment`)와 실행 파일 셋(`:60-72`)만 본다. 본 단계는 `prlimit`·`systemd-run`(`scripts/run-and-validate-provider.ts:119-124`)과 user manager 254 이상(`:494-503`)을 쓴다. `docs/work/reference/gates.md:92` 기준 위반. 시험에 그 사례가 없다(`tests/unit/system-test-prerequisites.test.ts`). **낮춘 이유:** 뒤 단계가 원인 이름을 대며 멈춘다(`provider cgroup unavailable: …`, `:120-123`, `:502`). G5가 막으려던 "원문 오류"가 아니다. D8 판정은 desktop에서 점검이 namespace로 먼저 멈추고 「충족」은 runner로만 세므로 merge 판정이 틀리지 않는다. PR #19는 FE-GATE-013을 root systemd 컨테이너로 옮긴다(FETCH_HEAD `docs/work/reference/gates.md` 3절) | `tests/unit/system-test-prerequisites.test.ts`: 가짜 host에서 `show-environment` 0, `systemctl --user show` 실패 → user manager를 이름으로 대는 실패 기대(지금 `[]`). 실험 X-GD03(선택) | 아니오 | 관련: PB/1105-12-01(같은 파일, 그때는 namespace만 고침). 다른 빈틈이라 중복 아님 |
|
||||
| L8/GD-04 | 확인·등급 조정 | Low·P3 | 성립: `AGENTS.md:29`, `docs/work/reference/gates.md:54`, `docs/work/experts.md:70`, `scripts/hooks/README.md:29`, `scripts/hooks/hooks.py:75-83`(`LAPTOP_ONLY`에 `.claude/`, `CLAUDE.md`, `src/**/AGENTS.md`), `scripts/tests/test_hooks.py:246-247`이 노트북 검사로 끝난다고 한다. 코드는 그 문서를 desktop `verify:documentation`이 본다(`scripts/lib/docs-system.ts:728-731`, `scripts/verify-documentation-readiness.ts:343-346`). `.claude/rules/docs.md:15`, `docs/work/README.md:75`, `docs/work/docs-writing.md:41-42`와 갈렸다. PR #19는 `AGENTS.md:28`만 바꾸고 `:29`는 그대로다. **낮춘 이유:** FE-GATE-005(`tests/unit/documentation-readiness.test.ts`)가 merge 전에 잡는다. 늦게 알 뿐 틀린 merge 답은 없다. 같은 모양인 GD-05·GD-10·GD-11과 같은 등급 | `scripts/tests/test_hooks.py:246`: `.claude/rules/x.md`를 고친 뒤 stop이 N5 알림을 낸다(지금 `None`, 시험이 반대를 단언하므로 시험을 뒤집는다) | 아니오 | 없음 |
|
||||
| L8/GD-05 | 확인·등급 조정 | Low·P3 | 성립: `.claude/rules/gates-and-budgets.md:21-22`가 `scripts/check-*.ts`를 고칠 때 "거절 fixture를 함께 둔다"면서 확인은 `scripts/verify.sh merge`만 시킨다. 그 fixture는 main 단계 FE-GATE-029에 있다(`config/ci/gates.json` stages `main`). **낮춘 이유:** main 단계 이동과 그 위험은 소유자 결정이다(`f6b2b96c` 본문 "위험: 검사기를 망가뜨린 PR은 merge를 통과하고 main에서 빨개진다"). 스킬 셋(`.claude/skills/fe-security/SKILL.md:71`, `fe-design-system/SKILL.md:76`, `fe-testing/SKILL.md:61`)과 `docs/work/reference/gates.md:118`이 이미 FE-GATE-029를 말한다. 남은 것은 경로 규칙 한 줄 | 없음(문장). GD-01 고치기 전에는 `gate FE-GATE-029`로 적는다 | 아니오 | 관련: GD-14(같은 결정의 색인 누락) |
|
||||
| L8/GD-06 | 확인 | Low·P3 (구조적 위험) | `scripts/verify-documentation-readiness.ts:307-316` `COMMAND_HEADS`에 `scripts/verify.sh`·`python3`가 없다. 공백 든 토큰은 `namedPath`가 버린다(`:285-288`). script 이름은 `:395-400`의 두 꼴만 본다. 문서는 일반적으로 본다고 적는다(`docs/work/reference/gates.md:107`, `docs/README.md:174`). 지금 틀린 참조 0이라는 리뷰어 대조를 반박할 근거는 못 찾았다 | `tests/unit/documentation-readiness.test.ts:234-254` `it.each`에 세 꼴(`scripts/verify.sh exec -- node scripts/no-such.ts`, `python3 scripts/no-such.py`, `scripts/verify.sh script no:such-script`)을 더해 실패 기대(지금 통과) | 아니오 | 없음 |
|
||||
| L8/GD-07 | 확인 | Low·P3 | `docs/operations/ci-quality-gates.md:111-127`이 범위를 1절 현재 계약 문서로 적고 "수치 … 검사하지 않는다"고 쓴다. 코드는 살아 있는 문서 전부(`verify-documentation-readiness.ts:343-346`)와 숫자 복사 검사(`docs-system.ts`, `docs/README.md:175` `number`)를 돈다. `docs/work/reference/gates.md:106`의 "기록은 머리 블록만"도 결정 기록 본문의 언어·문체 검사(`docs-system.ts:281-283`, `:523-526`, `DECISION_FOLDER` `:77`)와 다르다 | 없음(문장) | 아니오 | 없음 |
|
||||
| L8/GD-08 | 확인 | Low·P3 | `docs/manual/reference/create-feature.md:3`(모든 merge 게이트 통과), `:117-126`(출력 예시에 `Next:` 3 없음), `:136-145`(되돌리기에 초기 JS 기록 다시 쓰기 없음). 실제 출력은 3을 낸다(`scripts/create-feature.ts:1775`). 드릴도 다시 쓴 뒤 게이트를 돈다(`scripts/test-feature-scaffold.ts:71-90`). 매뉴얼 01(`:810`)과 03(`:262`)은 맞다. 참조 문서만 빠졌다 | 없음(문장). 실험 X-GD08(선택) | 아니오 | 없음 |
|
||||
| L8/GD-09 | 확인 | Low·P3 | `scripts/hooks/hooks.py:86` `VERIFY` 정규식이 `scripts/verify.sh` 뒤 첫 낱말을 단계로 보고 `:290-293`이 `docs`·`hooks` 밖이면 참이다. `sed … scripts/verify.sh && ls`(`&&`), `grep … scripts/verify.sh config/ci/gates.json`, `git log -- scripts/verify.sh docs/work`, `--dry-run` 모두 참이 된다. ssh 쪽은 명령 어디든 `vitest`가 있으면 참(`:85`, `:289`). README는 "돌린 명령"을 센다고 적는다(`scripts/hooks/README.md:28`) | `scripts/tests/test_hooks.py:237` `test_laptop_commands_and_other_hosts_do_not_count`에 다섯 입력을 더해 False 기대(지금 True) | 아니오 | 없음 |
|
||||
| L8/GD-10 | 확인 | Low·P3 | `.claude/rules/gates-and-budgets.md:2-10` paths와 `:23` "N6이 이 파일들의 편집을 알린다". `scripts/hooks/hooks.py:57-66` `GATE_STANDARDS`에는 `config/ci/gates.json`, `.gitea/**`, `scripts/run-ci-gate.ts`, `scripts/contracts/**`, `scripts/check-*.ts`가 없다. `scripts/hooks/README.md:24`의 N6 범위가 코드와 맞고 규칙 문장만 넓다 | 코드를 넓히면 `test_hooks.py`에 `config/ci/gates.json` 편집 → N6 알림 사례 | 아니오 | 없음 |
|
||||
| L8/GD-11 | 확인 | Low·P3 | `.claude/rules/tests.md:25`가 `scripts/verify.sh script test:unit`(전체 suite, `package.json` `test:unit`) 또는 맨 `ssh desktop`(공유 checkout, PATH에 node 없음 `docs/work/operate.md:42`)을 권한다. 정본은 `operate.md:41`(`exec -- node scripts/run-vitest.ts run <파일>`), `:35`(공유 checkout 금지). `operate.md:97`도 같은 문서 안에서 어긋난다 | 없음(문장) | 아니오 | 없음 |
|
||||
| L8/GD-12 | 반박(제안으로만 남김) | — | 여섯 문장이 틀린 사실을 말하지 않는다. 목록 상수 `REMOVAL_FIXTURE_COPY_TARGETS`·`REMOVAL_FIXTURE_DOCUMENT_TARGETS`는 지금도 `scripts/lib/removal-fixture.ts:35`, `:52`가 내보내고 한 줄로 등록부 집합을 고른다. 등록부도 자기 설명에서 그 파일을 읽는 곳으로 적는다(`config/repository-layout.json:13-14`). "이 목록 하나만 쓴다"(`docs/work/reference/structure.md:119`)도 맞다. 편집 위치가 한 단계 건너라는 점만 남는다. 원하면 "등록부 `fixture-copy`·`fixture-documents`(`removal-fixture.ts`가 고른다)"로 다듬는다 | — | 아니오 | 없음 |
|
||||
| L8/GD-13 | 확인 | Low·P3 (작은 진단 누락) | `scripts/run-ci-gate.ts:58-66`는 버퍼에만 쌓고 `:243-246`은 `FE-GATE-0NN <name>: FAIL`만 낸다. desktop `/tmp/claude-gates/r9fe-base/FE-GATE-013.log` 전체가 세 줄이다(E2, 읽음). 원인은 `gate-artifacts/FE-GATE-013.txt`에만 있다. workflow는 로그를 `if: always()`로 올린다(`.gitea/workflows/quality-gates.yml:70` 등)라 G12의 막는 기준 일부는 지킨다. 실패 줄이 로그 경로조차 말하지 않는 것이 남는다(`.claude/rules/gates-and-budgets.md:21`) | FAIL 줄 조립을 `scripts/lib/`로 빼 단위 시험: 실패 명령 id·`artifacts/quality/gates/<ID>.txt` 경로·마지막 줄을 담는지(지금 실패). 또는 `tests/system/ci-runner/ci-evidence-freshness.test.ts`에 같은 단언 | 아니오 | 관련: PB/1105-12-01 ②(대기 함수 메시지에 stderr 없음). 다른 위치 |
|
||||
| L8/GD-14 | 확인 | Low·P3 | `docs/work/reference/decisions.md` 2.1·2.2절에 FE-GATE-029 main 단계·`*:fixture` 이동·기준선 삭제 행이 없다. `decisions.md:3`이 결정의 색인이라고 적는다. **정정:** 출처가 커밋 본문뿐은 아니다. 기준선 삭제는 `docs/operations/ci-quality-gates.md:17-19`에 "소유자 결정"으로, main 단계는 `:11-12`에 적혀 있다. 색인만 빠졌다 | 없음 | 아니오(이미 난 결정의 색인) | 중복: PB/PB-N1 둘째 줄(같은 색인 누락) |
|
||||
| L8/GD-15 | 확인 | Low·P3 | `docs/work/docs-writing.md:31`이 다른 문서의 리뷰 ID 꼴을 `MMDD/NN-MM`으로 정한다. 라운드 없는 ID가 살아 있는 문서에 있다: `docs/architecture/layers.md:106`, `:147`, `:168`, `:189`, `docs/operations/ci-quality-gates.md:39`, `:90`, `:127`, `:133`, `docs/architecture/optional-adapter-recipes.md:204`, `docs/architecture/static-delivery.md:37`, `docs/operations/performance-evidence.md:104`, `docs/operations/release-cache-rollback.md:59`, `docs/security/browser-boundary.md:12`, `docs/security/supply-chain.md:44`, `:67` 등(리뷰어의 grep을 다시 돌려 같은 줄을 봤다). 기계 검사는 `CHANGELOG.md`만 본다(`tests/unit/changelog-review-ids.test.ts`) | `tests/unit/changelog-review-ids.test.ts`의 판정을 살아 있는 문서에 거는 시험(지금 위 줄에서 실패) | 아니오 | 없음 |
|
||||
| L8/GD-16 | 확인 | Low·P3 | `docs/work/reference/gates.md:52` "merge에 더해 `check:bundle`(FE-GATE-012)". FE-GATE-012는 merge `gateIds`에 있다(`config/ci/gates.json` stages). `docs/work/reference/performance.md:6`은 맞게 쓴다 | 없음(문장) | 아니오 | 없음 |
|
||||
| L8/GD-17 | 확인 | Low·P3 | `README.md:221`, `docs/manual/01-add-a-feature.md:817`이 지금 동작(변수 표)을 `docs/design/2026-07-26-frontend-platform-testing-strategy-design.md` 13.6절로 가리킨다. 그 설계서 머리 블록(`:4`, `:7`)은 「확인 안 함」, 현재 정본 `docs/testing/taxonomy.md`인데 taxonomy에 표가 없다. 코드 정본은 `scripts/lib/run-isolation.ts:119` `TEST_PORT_VARIABLES`. `docs/README.md:70`과 어긋난다 | S-06과 같은 문서 검사(살아 있는 문서가 `docs/design/` 절을 지금 동작의 출처로 가리키면 실패) | 아니오 | 같은 원인: L2/S-06, L9/R-02 |
|
||||
| L8/GD-18 | 확인 | Low·P3 (미검증 성격) | `docs/manual/04-paired-backend-session.md:10` "백엔드 `bbe944bd` 기준" vs pin `45d2a478`(`docs/README.md:48`). 두 커밋 사이 10커밋에 인증 관련 파일이 바뀌었다(`docs/manual/07-authorization.md`, `SampleDemoAccountsProductionGuard.java` 등, 백엔드 `git diff --name-only`). `AGENTS.md:3`의 `compose.yaml`은 pin 트리에 없고(`docker-compose*.yml`뿐) main에만 있다. 04의 사실이 pin과 다른지는 확인 못 했다 | 실험 X-01(drift). 04는 pin 트리에서 다시 대조 | 조건부(pin을 올려 맞추면 S-05와 같은 결정. 문서를 pin 기준으로 다시 대조만 하면 아니오) | 관련: L2/S-05 |
|
||||
| L8/GD-19 | 확인 | Low·P3 (구조적 위험, 사본이 아직 같음) | `docs/work/README.md:73`의 상한 여섯은 `scripts/check-work-docs.py:70-77` 상수 사본이다. `CLAUDE.md:10` "`fe-*` 스킬 9개"는 `.claude/skills/fe-*` 개수(9) 사본이다. 둘을 대조하는 시험이 없다(`scripts/tests/test_claude_setup.py:212`은 스킬 명단만, 문장 숫자는 안 본다). `.claude/rules/docs.md:13`(숫자를 옮겨 적지 않는다) | 없음 | 아니오 | 없음 |
|
||||
|
||||
## 2. 실험 목록
|
||||
|
||||
모두 총괄이 desktop에서 한 번씩, 실험마다 작업 폴더를 되돌린다. 리뷰어가 낸 X-04·X-GD01a는 이미 증거가 있어 뺐다(X-04: `gate-artifacts/FE-GATE-010.txt:66` "12/13". X-GD01a: PR #19 `79a225b6` 본문의 desktop 측정 "parts만 009를 실패로 냈다").
|
||||
|
||||
| ID | 대상 | 명령 | 패치 | 기대 결과 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| X-V2-01 | S-01 | `scripts/verify.sh script check:architecture`(CI=true) 그리고 노트북 `python3 -m unittest discover -s scripts/tests -p test_hooks.py -k test_another_adapter_is_item_2_and_the_kernel_is_allowed` | scratchpad `r1-L2-patches/X-02a-widen-kernel.patch`, 되돌린 뒤 `X-02b-delete-kernel-rule.patch` | 두 패치 모두 `check:architecture` rc=0(CI 게이트 빈틈), hooks 시험은 FAIL(`꼭 지킬 것 2 의심` 줄 없음). 원래 규칙에서는 둘 다 통과 |
|
||||
| X-01 | S-05, GD-18 | 백엔드 main(`a7e38c10`)을 origin에서 따로 clone(desktop의 `~/workspace/clean-architecture-backend-template`은 `3d73b6f1`이라 쓰지 않고 건드리지 않는다): `git clone -q <백엔드 origin> /tmp/claude-gates/be-main && git -C /tmp/claude-gates/be-main checkout -q a7e38c10`, 그 뒤 `scripts/verify.sh exec -- node scripts/check-backend-contract-drift.ts --backend /tmp/claude-gates/be-main` | 없음 | exit 1. 실패 다섯: `docs/web/http-contract.md changed …`, scaffold source `scripts/new-feature.sh`, `…/domain-core/…/__Feature__.java.tmpl`, `…/application-core/…/__Feature__ErrorCode.java.tmpl`, `…/application-core/…/Create__Feature__UseCase.java.tmpl`. 참고: 리뷰어의 X-GD18(옆 checkout `3d73b6f1`, pin+2커밋)은 rc=0으로 끝날 것이라 S-05를 보이지 못한다 |
|
||||
| X-03 | S-02 | `scripts/verify.sh script check:architecture`(CI=true) | `r1-L2-patches/X-03-reexport-holes.patch`(`createContractHttpExecutor`는 http 배럴에 있다, `src/adapters/http/index.ts:7`) | rc=0. presentation이 routing·contribution 파일을 거쳐 http adapter 값에 닿는다 |
|
||||
| X-V2-02 | S-10 | `scripts/verify.sh exec -- node scripts/run-vitest.ts run tests/unit/runtime-adapters-credential-order.test.ts tests/unit/runtime-adapters-auth-profile.test.ts` | `src/bootstrap/runtime-adapters.ts` `reportServerUnauthenticated`(`:605-621`)에서 `Object.hasOwn(productCredentialProviders, …)` 블록을 ANONYMOUS 검사 위로 옮긴다 | 통과(변이가 살아남는다). RED 시험을 더한 뒤에는 실패해야 한다 |
|
||||
| X-GD01b | GD-01 | `scripts/verify.sh parts FE-GATE-029 --log r9-v2-parts029`와 `scripts/verify.sh gate FE-GATE-029 --log r9-v2-gate029`. PR #19 브랜치에서도 한 번 | `scripts/check-design-system.ts` 첫 줄에 `if (process.argv.includes("--fixture")) { process.stderr.write("unrelated crash\n"); process.exit(1); }`(L8 4절 패치) | parts는 `check:design-system:fixture`를 통과로 세고(main·PR #19 둘 다), gate는 `expected negative fixture identity`로 실패 |
|
||||
| X-GD02 | GD-02 | `scripts/verify.sh exec -- bash -c 'corepack pnpm -s create:feature invoice-feature && node scripts/run-vitest.ts run tests/unit/manual-code-blocks.test.ts'` | 없음 | 시험 실패, 출력에 `feature id invoice-feature is already a feature or context` |
|
||||
| X-GD02b | GD-02 | `scripts/verify.sh exec -- bash -c 'corepack pnpm -s create:feature order-feature --with-create --keyed && corepack pnpm exec playwright test tests/e2e/generated-feature.spec.ts --project=chromium'` | 없음 | beforeAll의 `addGeneratedFeature`가 같은 문구로 실패 |
|
||||
| X-GD03 | GD-03(선택) | `scripts/verify.sh exec -- bash -c 'systemctl show-environment >/dev/null; echo system=$?; env -u XDG_RUNTIME_DIR -u DBUS_SESSION_BUS_ADDRESS systemctl --user show --property=Version --value; echo user=$?'` | 없음 | system=0, user≠0이면 점검과 본 단계의 판정이 갈리는 호스트 조건이 재현된다 |
|
||||
| X-GD08 | GD-08(선택) | L8 4절 X-GD08 그대로 | 없음 | 마지막 `feature-shape-growth.test.ts`가 기록 drift로 실패 |
|
||||
@@ -0,0 +1,52 @@
|
||||
# round9 V3 반박 검증 — L3(시험)·L6(성능)
|
||||
|
||||
> round9 리뷰(2026-11-12, 대상 main `5250ff95`)의 영역 기록이다. 서브에이전트가 쓴 원문을 그대로 옮겼다. 바꾼 것은 이 인용 블록과, 작업 폴더 절대 경로를 `(작업 폴더)`로 줄인 것뿐이다. 발견 ID는 이 파일의 이름표(R-01 등)이고, 라운드 ID(`1112/NN-MM`)와의 대응은 [README](2026-11-round9-review.md) 15절이다.
|
||||
|
||||
|
||||
- 대상: `5250ff95`(HEAD). 읽기만 했다. desktop은 `/tmp/claude-gates/r9fe-base/`의 로그·junit만 읽었다.
|
||||
- w2-fe-2 PR #19: `origin/claude/w2-fe-ci-perf-dce080` = `ba72b865`(`git show FETCH_HEAD:<파일>`로만 읽음).
|
||||
- 판정 합계(24건): 확인 12 · 확인·등급 조정 3 · 반박 9(모두 「제안으로만 남김」) · 실행 필요 0. 확인한 것 중 영향 크기·등급을 가를 실험은 2절 목록이다.
|
||||
|
||||
## 1. 결과 표
|
||||
|
||||
| 원 ID | 판정 | 최종 등급 | 근거·반박 이유(file:line) | RED 위치 또는 실험 | 소유자 결정 필요?(이유) | 중복 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| L3/T-01 | 확인·등급 조정 | Medium·P2 → **Low·P3** | 성립: `tests/e2e/accessibility.spec.ts:130-137`이 `body`의 `animationDuration`을 보고 허용 목록에 초기값 `"0s"`가 있다. 앱의 animation은 `.ui-spinner` 하나다(`src/presentation/styles/theme/primitives.css:116`). 규칙(`responsive.css:86-95`)을 지워도 `body`는 `0s`라 통과한다. 다른 reduced-motion 검사 없음(`git grep`: 이 시험 하나). `APP_HOME.md:18`이 이 시험을 자동 증거로 든다. 등급: 규칙은 구현돼 있고 사용자 피해가 없다. "시험이 구현된 규칙을 고정하지 않는다"는 1105/01-04·02-04와 같은 모양(Low·P3)이고, 같은 결함을 낸 L5/A11Y-08도 Low·P3다 | `tests/e2e/accessibility.spec.ts`: 페이지에 `.ui-spinner`를 붙여 감소 설정 없음에서 `animation-iteration-count`=`infinite`(전제), `reduce`에서 `1`과 duration ≤ 0.01ms를 단언. 허용 목록에서 `"0s"` 삭제. 실험 V3-E01 | 아니오 | L5/A11Y-08(같은 원인) |
|
||||
| L3/T-02 | 확인 | Low·P2(E-02에서 한 엔진이라도 이른 return이면 Medium·P1) | 코드 모양 성립: `tests/browser-capabilities/opfs-runtime.spec.ts:352`, `:470`이 `if (!(await installOpfsTab(page, scope))) return;`, `installOpfsTab`은 지원 거절이면 `false`(`:252`). `.claude/rules/tests.md` 4번("첫 줄에서 return하지 않는가")을 어긴다. 증거 검사는 `<skipped`만 본다(`scripts/verify-browser-capability-evidence.ts:61-62`). 지금 실제로 이른 return 하는지는 모른다: r9fe-base capability junit에서 세 엔진 모두 2.6~7.9 s 걸렸지만 dev server 모듈 import 시간이라 근거가 못 된다. 기본 정책은 `allowAsyncWritableChunkFallback: true`(`src/adapters/storage/opfs/opfs-policy.ts:75`)라 1105 리뷰의 "WebKit 거절"은 이 정책에서는 확인되지 않는다. 같은 등급 선례 1101/10-01(첫 줄 return, Low·P2) | `opfs-runtime.spec.ts:352`, `:470`을 `expect(await installOpfsTab(...), "OPFS supported").toBe(true)`로. 실험 V3-E02 | 조건부 예. E-02에서 미지원 엔진이 나오면 L3가 낸 `test.skip`안은 쓸 수 없다: 증거 검사가 `<skipped`가 하나라도 있으면 FE-GATE-008을 실패시킨다(`verify-browser-capability-evidence.ts:61-62`). 지원 범위를 줄일지, 증거 규칙(게이트 기준)을 바꿀지는 소유자 결정 | 없음 |
|
||||
| L3/T-03 | 확인 | Low·P2 | 성립: mask 규칙(`scripts/check-test-evidence.ts:307-311`)을 혼자 돌리는 시험이 없다. `tests/unit/test-evidence-source-rules.test.ts:31-32` 주석은 "Each forbidden fixture is checked alone"인데 시험은 셋(`:34-50`)뿐이다. 디렉터리 전체를 돌리는 `check-test-evidence-fixture`의 기대 진단은 공통 접두어 `"Test evidence failed:"`(`config/ci/gates.json:118-123`, 출력 `check-test-evidence.ts:458`)라 다른 셋이 실패하면 통과한다. strict fixture 우회(`:394-398`)와 `forbidOnly`(`:385-388`)는 `if (!fixtureMode && !scenarioOnly)`(`:368`) 안이라 fixture로 못 시험한다. 두 문구를 찾는 시험 0건. 선례 1101/12-02(음성 fixture 없는 규칙, Low·P2) | `tests/unit/test-evidence-source-rules.test.ts`에 "rejects a screenshot mask over the whole UI"(mask fixture 단독, rc=1, `screenshot mask may not cover the whole UI`). e2e 규칙 둘은 검사 대상 폴더·설정을 인자로 받게 하고 거절 fixture 둘. 실험 V3-E03 | 아니오 | 없음 |
|
||||
| L3/T-04 | 확인 | Low·P3(구조적 위험) | 성립: `scripts/check-test-evidence.ts:391-398`이 `tests/e2e/*.spec.ts` 본문에 `"support/browser/strict-browser-test"` 글자가 있는지만 본다. `tests/browser-capabilities`·`tests/visual`·`tests/storybook`은 안 본다. 지금 우회는 `tests/browser-capabilities/chunk-load-error.spec.ts:1` 하나(이유 있음)와 `tests/e2e/preload-use.spec.ts:4`(의도한 혼용). 결함 패턴 G8의 통제("문구 검사는 ESLint 구문 규칙으로", `defect-patterns.md:22`)를 따르지 않는다 | `tests/fixtures/architecture` 방식 lint fixture: capability 폴더 spec이 `import { test } from "@playwright/test"` → lint 실패 기대. 지금은 아무 게이트도 실패 안 함 | 아니오 | 없음 |
|
||||
| L3/T-05 | 확인 | Low·P3(구조적 위험) | 성립: strict fixture는 fixture의 `page` 하나에만 listener·preload 추적을 붙인다(`tests/support/browser/strict-browser-test.ts:68-96`). 앱을 여는 두 번째 탭 7곳(`cross-context-invalidation.spec.ts:163`, `:226`, `opfs-runtime.spec.ts:341`, `:459`, `indexeddb-runtime.spec.ts:933`, `:985`, `:1190`)은 아무도 안 본다. `tests/e2e/service-worker-recovery.spec.ts:135-150`은 fixture와 갈라진 손 사본이다(preload 검사 없음, 무시 규칙 다름). 루트 `AGENTS.md` "갈라진 중복 복사본은 결함" | `tests/e2e/preload-use.spec.ts`처럼 verdict를 바꿔 기록을 읽는 시험: `page.context().newPage()`에서 `console.error("probe")` → 기록에 `console:error:probe`가 있어야 함. 지금은 없음 | 아니오 | 없음 |
|
||||
| L3/T-06 | 확인 | Low·P3(구조적 위험) | 성립: preload 검사는 끝에 열려 있는 문서만 본다(`tests/support/browser/preload-use.ts:34-35`, `:217`). A 탭은 reload로 B 문서가 된다(`tests/e2e/old-tab-chunk-recovery.spec.ts:241` `loads === 1`). 그래서 A 목록 허용(`:195`)은 A 문서에 닿지 않고 B 문서의 같은 이름 공유 청크만 가린다. 주석 `:181-188`("in the A tab …")이 검사 동작과 다르다 | RED 없음(허용 축소). 실험 V3-E04(A 목록 지우고 반복 통과) | 아니오 | 없음 |
|
||||
| L3/T-07 [w2-fe-2 파일] | **반박**(제안으로만 남김) | — | 핵심 근거가 틀렸다. (1) 사유는 여섯 파일 모두 사실이다: 여섯 파일은 모두 main·nightly scale 단계에만 있다(`scripts/scale/run-scale-profile.ts:71`, `:87`, `:91`, `:93`, `:109`, `:113`). (2) "parser를 merge 게이트 측정이 쓴다"는 틀렸다: FE-GATE-020은 `--initial-baseline`만 부른다(`scripts/test-feature-scaffold.ts:76-80`) → `measureInitialJavascriptCosts`(`scripts/scale/measure-feature-shape-growth.ts:377-379`, `:227`) → `measureInitialJavascript`(`:192-205`, "no typecheck"). parser는 수동 `--sizes` 실행의 `measureOnce`(`:282-307`)와 scale main의 `collect-tsc-diagnostics.ts:66`에서만 쓴다. 남는 것은 "CPU와 무관한 순수 parser 시험이 main tier에 있다"는 배치 제안뿐이다. PR #19는 이 파일을 안 바꾼다 | 해당 없음(제안: `tsc-diagnostics-parser.test.ts`를 `run-scale-profile.ts`의 pr tier로 옮기면 FE-GATE-005에서 돈다) | 아니오 | 관련만: 0929/12-07(예외 목록 담당, 결정 대기) |
|
||||
| L3/T-08 [w2-fe-2 관련: 시험 timeout] | 확인 | Low·P3 | 성립: `docs/work/reference/testing.md:39-40`은 자식 프로세스 시험의 값을 `childProcessTimeout(<ms>)`로 정한다고 적는다. 손 숫자 54곳(`git grep` 재현)이 남았고, 그중 직접 자식 프로세스를 띄우는 파일이 약 44곳이다(나머지 10곳은 scale·in-process 시험이라 규칙 대상이 아님 — 리뷰어 숫자가 조금 넓다). `PROCESS_HEAVY_TIMEOUT_MS = 30_000` 4벌(`tests/unit/risk-coverage.test.ts:34`, `tests/unit/security-followup-fixture.ts:26`, `tests/integration/provider-guardian-transaction.test.ts:28`, `tests/system/ci-runner/ci-artifact-contract.test.ts:65`). `docs/testing/taxonomy.md:104-106`이 옛 상수를 예로 든다(문서 둘이 다른 방법을 적음). PR #19는 `tests/setup.ts`를 Testing Library 지연 적재로만 바꾸고(`git diff HEAD FETCH_HEAD -- tests/setup.ts`) taxonomy는 15줄만 고쳐 이 항목은 그대로다 | `tests/unit/child-process-timeout.test.ts`: `docs/testing/taxonomy.md`와 `tests/**`에 `PROCESS_HEAVY_TIMEOUT_MS`가 없다는 단언(지금 실패) | 아니오 | 없음 |
|
||||
| L3/T-09 | 확인 | Low·P3 | 성립: 주석 "The API answers are the paired backend's Envelope, written out as in the generated feature's own tests"(`tests/e2e/generated-feature.spec.ts:26-27`). 429는 `RATE_LIMITED`·`SYSTEM`(`:62-68`, `:246`), 500은 `INTERNAL_ERROR`·`SYSTEM`(`:284`). 짝 백엔드는 `RATE_LIMIT_EXCEEDED`·`RATE_LIMIT`, `INTERNAL`(백엔드 `docs/registries/error-codes.yaml` 429·500 행). 생성 기능 시험도 `SYSTEM`을 안 쓴다(`scripts/create-feature-write-slice.ts:1011`, `:1024`, `:1062`). 판정은 status로만 해서 지금 결과는 같다(`src/adapters/http/backend-envelope.ts:69` category는 자유 문자열) | RED 없음(대역 교정). 원하면 unit에서 e2e `failure()` code가 `config/contracts/backend-idempotency-answers.json`의 code와 같은지 대조 | 아니오 | 없음 |
|
||||
| L3/T-10 | 확인 | Low·P3 | 성립: `test:e2e`는 `tests/e2e` 전체(`package.json:43`, `playwright.config.ts:23`), `test:a11y`는 `--grep @a11y`로 같은 spec을 다시 돈다(`package.json:58`). 같은 job에서 차례로 돈다(`.gitea/workflows/quality-gates.yml:141-146`). r9fe-base `FE-GATE-009.txt`에 `accessibility.spec.ts`·`generated-feature.spec.ts` @a11y가 다시 찍혔다. `fe-testing` 함정 9와 `testing.md:107`("같은 파일을 두 번 돌리지 않는지")를 어긴다 | RED 없음(실행 비용). 완료 기준: 한 merge에서 @a11y 시험이 엔진마다 한 번 | **예**. FE-GATE-008이 무엇을 도는지 바꾸는 게이트 구성 변경이다. 같은 모양의 1101/10-06(빠른 층 중복 실행)이 결정 대기라 그 결정에 붙인다 | 관련: 1101/10-06(같은 모양, 다른 층) |
|
||||
| L3/개선-1(이름이 본문에 없는 동작) | 반박(제안으로만 남김) | — | `tests/storybook/galleries.spec.ts:74` 이름 "duplicate toast"는 맞다(토스트 한 번, `:85`). 그러나 시험 이름 규칙이 repo에 없다(`.claude/rules/tests.md`, `testing.md` 전체) | — | 아니오 | 없음 |
|
||||
| L3/개선-2(한 시험이 행동 여럿) | 반박(제안으로만 남김) | — | GWT 규칙 없음. 리뷰어도 결함이 아니라고 적음 | — | 아니오 | 없음 |
|
||||
| L3/개선-3(이름에 경우 나열 137개) | 반박(제안으로만 남김) | — | 같은 이유. 휴리스틱 수치 | — | 아니오 | 없음 |
|
||||
| L3/개선-4(부재 단언을 고정 대기로) | 반박(제안으로만 남김) | — | 모양은 맞다(`tests/e2e/app-shell.spec.ts:65` 300 ms, `cross-context-invalidation.spec.ts:201`, `:270` 100 ms, `opfs-runtime.spec.ts:413`, `:512` 250 ms). 부하에서 실패가 아니라 통과 쪽으로 빠지는 모양이라 T3(흔들림) 규칙에 걸리지 않고, `fe-testing` 함정 4의 "다 그려질 때까지 기다리기"는 클릭 대상 이야기다. repo 약속 위반 아님 | — | 아니오 | 없음 |
|
||||
| L3/개선-5(`NO_COLOR` 부분 문자열 무시) | 반박(제안으로만 남김) | — | `tests/support/browser/strict-browser-test.ts:22` 맞다. 무시 범위를 정한 규칙이 없다 | — | 아니오 | 없음 |
|
||||
| L6/PF-01 | 확인·등급 조정 | Medium·P2 → **Low·P2**(V3-X2에서 기능 라우트 첫 진입이 lab 예산 500 ms를 넘으면 Medium·P2) | 성립: `src/presentation/routes/app-router.tsx:527-534`이 라우트 모듈과 들어간 기능만 함께 받고, 그 뒤에야 `loadActive(routeOwners(loaded))`로 나머지 기능 실행부를 받는다. 그 전에는 `RouteLoadingSurface`(`:602`). 목록은 처음부터 있다(`src/platform/routing/context-route-module.ts:53` `featureIds`). context의 기능을 함께 받는 것 자체는 계약이다(`docs/manual/02-decision-tables.md` 1절 "그 context의 기능들을 한 번에 지연 로드한다", `app-router.tsx:448-452`, `routeOwners` `:453`). 결함은 직렬 한 단계뿐이고, 커밋 `298201f3` 본문의 "왕복을 늘리지 않는다"는 들어간 기능에만 맞다. 등급: 첫 진입 왕복 하나, 측정 없음(lab이 session-required 라우트를 못 고름, 1105/15-04), repo 문서 약속 위반 없음 | (가)안 RED: 한 context 두 기능 fixture에서 둘째 기능 실행부 요청이 context-routes 청크 응답 끝보다 먼저 시작함을 단언(지금 실패). 위치: 새 e2e spec 또는 `tests/e2e/generated-feature.spec.ts`의 fixture 재사용. **주의:** L6의 X2 RED(둘째 실행부를 3초 잡아도 3초 안에 그림)는 (가)로는 계속 실패하고 (나)로만 통과한다. 실험 V3-X2 | (가) 아니오. (나) 예: `application.features.get`이 context 모든 페이지에서 된다는 보장(`app-router.tsx:448-452`)을 라우트 단위로 줄이는 계약 변경 | 관련: 1105/15-04(lab이 기능 라우트를 못 잼) |
|
||||
| L6/PF-02 | 확인·등급 조정 | Medium·P2 → **Low·P2** | 성립(산술): 상한 `assets: 256`(`src/contracts/service-worker.ts:14`), 생성기는 `assets/`의 해시 `.js`·`.css`를 모두 넣고(`scripts/generate-service-worker-assets.ts:70-101`) 넘으면 개수 없는 문구로 던진다(`:102-104`). 기록의 25기능 run은 초기 21 + lazy 235 = JS 256개(`config/scale/feature-shape-growth.json` runs[2] build)라 CSS 하나로 257이다. 기록 summary는 다음 한계를 typecheck 메모리로 적는다(`config/scale/feature-shape-ceilings.json:8`). SW `ACTIVE`는 지원 구성이다(`src/features/product-capabilities.ts:20-23`). 기본 예산으로는 약 12기능에서 초기 JS가 먼저 걸리지만, 25기능 초기 JS 211,739 B는 예산보다 4,891 B만 크다. 등급: 빌드가 크게 실패하고(조용한 결함 아님) 사용자 피해가 없다. 남는 것은 기록 누락과 개수 없는 문구(G12) | `tests/unit/service-worker-web-push-remediation.test.ts`(이미 `collectStaticAssets`를 부름, `:105-117`)에 해시 `.js` 257개 dist fixture → 오류 문구가 `257`과 `256`을 담는지. 지금 실패. 실험 V3-X3(경계 기능 수) | 상한 256이나 precache 범위를 바꾸는 것은 예(SW 계약). 문구·기록 축 추가는 아니오 | 없음 |
|
||||
| L6/PF-03 | 확인 | Low·P3 | 성립: `src/presentation/styles/theme.css:1` `@import "tailwindcss";`에 `source()`가 없다. r9fe dist CSS의 `@layer utilities`에 규칙 40개(3,122 B). 출처가 src 밖인 것 확인: `shadow/canary`는 `docs/architecture/backend-api-and-server-state-contract.md`에만, `sepia`는 `tests/unit/color-scheme.test.ts`에만, `cursor-not-allowed`는 `tests/unit/realtime/fetch-sse-connection.test.ts`에만, `!relative`는 `scripts/*`에만. 지금 src CSS에 같은 이름 class는 없어 스타일 충돌은 아직 없다 | 빌드 CSS에 `.shadow\/canary`가 없음을 보는 unit(예: `tests/unit/design-system-initial-chunk.test.ts`의 빌드 재사용). 지금 실패. 실험 V3-X1 | `source("../../")`(src만)는 아니오. `source(none)`(제품이 유틸리티 class를 못 씀)은 fe-design-system 계약이라 예 | 관련: 1101/15-03(CSS 예산 없음) |
|
||||
| L6/PF-04 | 확인 | Low·P3 | 성립: build id는 `render-boot-failure` 청크에만 있고(r9fe dist `grep gitea-1-1`), 그 이름을 담은 것은 `boot`, `boot` 이름을 담은 것은 `index`뿐이다(dist 전체 `grep -l`). 세 파일 77,572 + 4,446 + 897 = 82,915 B = 초기 JS 194,403 B의 42.7%(`r9fe/bundle.json`). boot에 zod 17·@tanstack/query-core 16·lucide-react 18 모듈(`vite-module-inventory.json`). `feature-platform` 그룹은 기능 실행부가 있을 때만 생긴다(`vite.config.ts:121-135`). 현재형 주석 `vite.config.ts:252-254`("renames 44,297 B")와 운영 문서 `docs/operations/performance-evidence.md:248`(22.0%)이 지금 빌드와 다르다 | `tests/unit/build-environment-bundle.test.ts:79-90`의 react-dom 단언 옆에 zod(`__zod_globalRegistry`를 담은 청크) 이름이 `VITE_BUILD_ID`만 다른 두 빌드에서 같다는 단언. 지금 실패. 실험 V3-X4 | 아니오(초기 파일 17→18은 상한 32 안) | 없음 |
|
||||
| L6/PF-05 | 반박(제안으로만 남김) | — | 모양은 맞다: `src/bootstrap/register-service-worker.ts:5` 정적 import, 선택 `null`(`src/features/product-capabilities.ts:34`)이면 `:35-37`에서 `null`, boot에 `CLIENT_DRAIN_REQUEST` 2회·`ACTIVATE_DRAIN_TIMEOUT` 3회. 그러나 "선택하지 않은 기능은 초기 청크에서 빠진다"는 약속 표(`docs/architecture/optional-adapter-recipes.md:29-39`, "composition 전에는 tree-shaken")에 SW 페이지 컨트롤러(`src/adapters/service-worker`)는 없다. B3는 배럴·side effect 판정 때문인 경우이고 이것은 런타임 분기다. 리뷰어도 개선 제안으로 냈다 | — | 아니오 | 없음 |
|
||||
| L6/PF-06 | 확인 | Low·P3 | 성립: `buildManifestArtifactSchema`(`src/contracts/release-artifacts.ts:249`), `runtimeConfigArtifactSchema`(`:201`), `releaseManifestArtifactSchema`(`:244`)를 src에서 쓰는 곳이 없다(src 사용처는 V1·V2 schema만: `src/bootstrap/load-release-manifest.ts:7-12`, `src/bootstrap/runtime-config-schema.ts:3-9`). 스크립트는 `scripts/contracts/release-artifacts.ts:3` 재수출로 쓴다. 그런데 boot 청크에 `moduleInventoryHash`가 있다(r9fe dist). 결함 패턴 B3(side effect 판정 때문에 남는 코드) 그대로 | `tests/unit/design-system-initial-chunk.test.ts`의 `initialJavascript()`로 초기 JS에 `moduleInventoryHash`가 없음을 단언. 지금 실패 | 아니오 | 없음 |
|
||||
| L6/PF-07 | 반박(제안으로만 남김) | — | 모양은 맞다: `dist/index.html`은 entry와 `preload-helper`만 modulepreload, boot 그래프 16파일은 entry 실행 뒤 `__vite__mapDeps`로 한 번에 요청(왕복 하나, 단계마다가 아님). entry의 dynamic import는 09-03 결정(`src/bootstrap/main.tsx:3-12`)이고 LCP는 lab(FE-GATE-026)이 예산으로 잰다. 어긴 약속 없음 | — | 아니오 | 없음 |
|
||||
| L6/PF-08 | 반박(제안으로만 남김) | — | 모양은 맞다: `scripts/lib/storybook-static.ts:18-25`, `playwright.storybook.config.ts:40`, `playwright.visual.config.ts:86`, r9fe `FE-GATE-008.txt:301`, `:321`. 같은 빌드를 두 번 하지 말라는 repo 약속은 없다(testing.md 6절은 시험 파일 중복). 재사용하면 낡은 빌드를 쓰는 G4 위험이 새로 생긴다 | — | 아니오 | 없음 |
|
||||
| L6/PF-09 [w2-fe-2 파일] | 확인 | Low·P3 | 성립: `package.json:157` `"dependency-cruiser": "18.1.0"`, 실행·import 0건. **PR #19가 이미 고쳤다**: `66138440` "쓰지 않는 dependency-cruiser를 지운다", `git show FETCH_HEAD:package.json`·`pnpm-lock.yaml`에 0건, 의존성 기준선 재승인 포함 | PR #19 merge 뒤 닫힘 확인만. 따로 고칠 것 없음 | 아니오 | PB/0929/12-05(같은 원인) |
|
||||
|
||||
## 2. 실험 목록
|
||||
|
||||
모두 desktop, 한 checkout에서 하나씩, 실험마다 작업 폴더를 되돌린다(`git checkout -- .` 뒤 `git status` 비었는지). 브라우저 실행은 실행마다 다른 `TEST_RUN_ID`.
|
||||
|
||||
| ID | 대상 | 명령 | 패치 | 기대 결과 |
|
||||
|---|---|---|---|---|
|
||||
| V3-E01 | T-01 | `scripts/verify.sh exec -- corepack pnpm exec playwright test tests/e2e/accessibility.spec.ts -g "reduced-motion"`, env `TEST_RUN_ID=v3-e01`, 15분 | `src/presentation/styles/theme/responsive.css` 86~95줄(`@media (prefers-reduced-motion: reduce) {…}`) 삭제 | 세 엔진 모두 **통과**(거짓 통과 확인). L3 E-01과 같다 |
|
||||
| V3-E02 | T-02 | `scripts/verify.sh exec -- corepack pnpm exec playwright test --config playwright.capabilities.config.ts tests/browser-capabilities/opfs-runtime.spec.ts`, env `TEST_RUN_ID=v3-e02`, 10분 | `opfs-runtime.spec.ts:352`, `:470`의 `if (!(await installOpfsTab(page, scope))) return;` → `expect(await installOpfsTab(page, scope), "OPFS supported").toBe(true);` | 세 엔진 통과면 T-02는 Low·P2 그대로(지금 가린 것 없음). 실패 엔진이 있으면 Medium·P1로 올리고 소유자 결정(지원 범위 또는 증거 규칙). L3 E-02와 같다 |
|
||||
| V3-E03 | T-03 | ① `scripts/verify.sh exec -- node scripts/run-vitest.ts run tests/unit/test-evidence-source-rules.test.ts` ② `scripts/verify.sh exec -- sh -c 'corepack pnpm check:test-evidence:fixture; echo rc=$?'`, 5분 | `scripts/check-test-evidence.ts:307-311`(`wholeUiMask` 블록) 삭제 | ① 4건 통과 ② rc=1, `Test evidence failed:` 출력 → 변이가 살아남는다. L3 E-03과 같다 |
|
||||
| V3-E04 | T-06 | `scripts/verify.sh exec -- corepack pnpm exec playwright test tests/e2e/old-tab-chunk-recovery.spec.ts --repeat-each=5`, env `TEST_RUN_ID=v3-e04`, 25분 | `old-tab-chunk-recovery.spec.ts:195` 한 줄(A 목록) 삭제 | 세 엔진 15/15 통과(허용 절반이 쓰이지 않음). L3 E-04와 같다 |
|
||||
| V3-X1 | PF-03 | L6 X1 스크립트 그대로, 15분 | 스크립트 안에서 `docs/README.md` 끝에 `underline` 추가 → 되돌림 → `theme.css` 1줄을 `@import "tailwindcss" source("../../");`로 | A·B CSS 파일 이름이 다르고 B에 `.underline`. C에 `.shadow\/canary` 없음. `visual_rc=0` |
|
||||
| V3-X2 | PF-01 | L6 X2 spec을 쓰되 지연을 빼고 시각을 기록: `page.on("request")`와 `page.on("requestfinished")`로 context-routes 청크 응답 끝 시각과 `beta-feature` 실행부 요청 시작 시각을 남긴다. 명령 `scripts/verify.sh exec -- corepack pnpm exec playwright test tests/e2e/context-entry-probe.spec.ts --project=chromium`, 10분. 같은 spec에서 첫 화면 heading까지 시간을 5회 잰다 | L6 X2의 새 파일 패치에서 `page.route(... setTimeout 3000 ...)` 줄을 빼고 위 기록과 `expect(betaStart).toBeLessThan(routesEnd)`를 넣는다 | 지금: `betaStart ≥ routesEnd`(직렬, 실패). (가) 수정 뒤 통과. heading 시간이 기능 하나 context보다 한 묶음(약 40~100 ms) 길면 PF-01 영향 확인 |
|
||||
| V3-X3 | PF-02 | L6 X3 스크립트 그대로, 20분 | 스크립트 안에서 `SERVICE_WORKER`를 `ACTIVE`로 바꾸고 생성 기능 24·25개 | 24 rc=0(자산 ≤ 256), 25 rc≠0과 `Static asset count exceeds its bound.`. 경계가 다르면 그 기능 수·자산 수를 적는다 |
|
||||
| V3-X4 | PF-04 | L6 X4 스크립트 그대로, 10분 | 없음(빌드 id만 바꿔 두 번, 기능 1개 더해 두 번) | 기능 0개: 이름이 바뀌는 초기 JS 약 82,915 B(42.7%). 기능 1개: 그보다 작음. 문서 값 44,297 B와 비교 |
|
||||
@@ -0,0 +1,105 @@
|
||||
# round9 V4 반박 검증 — L4(UX·디자인 시스템) · L5(접근성)
|
||||
|
||||
> round9 리뷰(2026-11-12, 대상 main `5250ff95`)의 영역 기록이다. 서브에이전트가 쓴 원문을 그대로 옮겼다. 바꾼 것은 이 인용 블록과, 작업 폴더 절대 경로를 `(작업 폴더)`로 줄인 것뿐이다. 발견 ID는 이 파일의 이름표(R-01 등)이고, 라운드 ID(`1112/NN-MM`)와의 대응은 [README](2026-11-round9-review.md) 15절이다.
|
||||
|
||||
|
||||
대상: HEAD `5250ff95`. 읽기만 했다. 노트북·desktop에서 아무것도 실행하지 않았다. 판정 기준은 brief-verify.md, review-criteria.md 2·3절, decisions.md, 렌즈 스킬 `fe-ux`·`fe-design-system`·`fe-a11y`, `src/presentation/AGENTS.md`, `docs/styling/design-tokens.md`, `docs/accessibility/manual-checklist.md`.
|
||||
|
||||
## 0. 결론
|
||||
|
||||
- 35건 중 **확인 23 · 확인·등급 조정 10 · 반박 1 · 실행 필요 1**.
|
||||
- 중복 둘을 합치면 서로 다른 결함은 33건이다: L4/UX-05 = L5/A11Y-03, L4/DS-02 = L5/A11Y-04. 그 밖에 L5/A11Y-08 = L3/T-01이다.
|
||||
- 반박: L5/A11Y-12. 그리고 세 발견의 일부를 반박했다: UX-01의 「행동 버튼 없음」, UX-03의 ProgressBar, A11Y-03의 Pagination.
|
||||
- 등급을 내린 것:
|
||||
- DS-01: Medium·P2 → Low·P2
|
||||
- DS-02: Medium·P2 → Low·P2, 구조적 위험
|
||||
- UX-01: P2 → P3
|
||||
- DS-03: P2 → P3
|
||||
- A11Y-05: P2 → P3
|
||||
- A11Y-07: P2 → P3
|
||||
- 등급을 올린 것:
|
||||
- UX-05: P3 → P2. A11Y-03과 등급을 맞췄다.
|
||||
- A11Y-08: P3 → P2. 같은 T2 모양인 1101/10-01이 Low·P2였다. L3/T-01의 Medium은 내려야 한다.
|
||||
- 성격만 바꾼 것(등급은 그대로): UX-06과 DS-05는 「구조적 위험」이다.
|
||||
- L4가 「미검증」으로 낸 DS-04는 계산으로 확인했다(pixelmatch YIQ 기준, 아래 표).
|
||||
- 인용 줄 번호가 틀린 곳이 있다. 내용은 맞다.
|
||||
- L4 DS-01·DS-05·1절: `component.css:167-177` → 실제는 `component.css:14-24`다. 파일이 43줄이다.
|
||||
- L4 DS-06: `semantic.css:82`·`:85-96`·`:124-152` → 실제는 `:17`·`:20-31`·`:59-87`이다. 파일이 88줄이다.
|
||||
- L5 A11Y-16: 파일은 `examples/platform-overview-page.tsx`가 아니라 `src/presentation/examples/platform-overview-page.tsx`다.
|
||||
|
||||
## 1. 결과 표
|
||||
|
||||
| 원 ID | 판정 | 최종 등급 | 근거·반박 이유(file:line) | RED 위치 또는 실험 | 소유자 결정 필요?(이유) | 중복 |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| L4/UX-01 | 확인·등급 조정 | Low·P3 | **성립:** `src/presentation/i18n/catalog.ts:88-89`(en `:294-295`) "이 화면은 인증 연동 지점을 확인하기 위한 보호 라우트입니다."가 생성 기능(`scripts/create-feature.ts:578`, `scripts/create-feature-write-slice.ts:130`, 모두 `session-required`)의 로그인 전 최종 사용자에게 보인다. `:78-79` "코드에는 포함되어 있으며 운영자가…"도 같다. PRODUCT 원칙 1과 fe-ux 함정 11을 어긴다. **반박한 부분:** 「행동 버튼 없음」. 세 표면은 `AppShell`의 자식 라우트라(`app-router.tsx:689`) 셸 탐색이 늘 있다. 문구도 고칠 길을 말한다(`catalog.ts:75-76`). 근거로 든 routing 7.5절은 머리 블록이 「기록 · 설계서」다. `route.auth.integration.*`는 `createUnavailableSessionAdapter`(`src/adapters/auth/external-session-adapter.ts:167-169`), 즉 배포 구성이 깨진 상태라 운영자 문구가 일부 맞다. **등급:** 남는 것은 문구다. 3절 「낡은 문장」 꼴로 P3 | `tests/unit/i18n-contract.test.ts`: `route.auth.required.description`·`route.disabledFeature.description`의 ko·en에 `/라우트\|연동 지점\|seam\|코드에는 포함\|운영자\|operator/`가 없다고 단언한다. 지금 실패한다 | 아니오 | — |
|
||||
| L4/UX-02 | 확인 | Low·P2 | (a) `src/presentation/forms/use-app-form.ts:432-437`: 재전송이 쓰기 전에 거절되면 `setFormErrors(["form.resendLater"])`. 생성 작성 페이지가 이것을 `ErrorSummary`에 넘긴다(`scripts/create-feature-write-slice.ts:698-705`). 제목은 늘 `form.errorSummary`다(`src/presentation/forms/form-components.tsx:56-62`, `catalog.ts:126`). 이것은 **VD-04 결정 8**("입력 오류가 아닌 저장 실패는 ErrorSummary에 넣지 않는다", `docs/adr/VD-04-native-form-facade.md:40`)과 data-flow 8절 5a를 어긴다. 커밋 `25685871` 본문의 (i)안은 D10(결과 불명과 키를 지킨다)을 구현하는 방법이다. 표면은 결정하지 않았다(`decisions.md` 2.2 D10 문장). (b) `:313-317`: 선언한 409가 `form.conflict`가 되어 같은 제목 아래 나온다. VD-04 결정 5(`:35`)를 어긴다. **반박 시도:** L5 5절은 409를 「결함 아님」으로 봤지만 포커스만 본 판정이라 이 표면 문제와 다르다 | `tests/component/form-foundation.test.tsx:1155` 시험의 harness가 실제 `ErrorSummary`를 그리게 한다. 재전송 거절 뒤 `queryByRole("heading", { name: KO_MESSAGES["form.errorSummary"] })`가 `null`인지 단언한다. 선언한 409 경로도 같은 꼴이다. 지금 실패한다 | 아니오. 결과 상태와 D10은 그대로 두고 표면만 바꾼다. 다만 `formErrors`에서 두 문구를 빼면 이미 생성된 페이지의 표시가 바뀐다. 커밋 본문에 이행 안내를 적는다 | 관련: 이월 1103/03-01 (3). 같은 409의 `refusalMessages` 경로다(r1-PA-prior) |
|
||||
| L4/UX-03 | 확인 | Low·P3 | `scripts/create-feature.ts:856`·`:864`·`:1203-1204`: `count: query.data.total`을 그대로 넣는다. `src/presentation/i18n/message-contract.ts:115-118`은 `String(value)`만 한다. `catalog.ts:365` en에 단수형이 없다(`text-area.tsx:66-71`. 단 `maxLengthMessage` prop으로 덮을 수 있다). `useLocale().number`·`plural`을 쓰는 화면 코드가 0곳이다. **반박한 부분:** ProgressBar `%`(`progress-bar.tsx:13`)는 ko·en 결과가 같아 사용자 영향이 없다. 제안으로만 남긴다 | (1) 생성 목록: `tests/e2e/generated-feature.spec.ts`의 목록 응답 total을 12345로 하고 "총 12,345개 항목"을 기대한다. 또는 `tests/unit/create-feature.test.ts`에서 생성된 목록 페이지가 `number(`를 쓰는지 본다. (2) `tests/component/ui-primitives.test.tsx`: en-US, `maxLength=5`, 4자 → "1 character remaining". 둘 다 지금 실패한다 | 아니오 | 관련: L5/A11Y-17(같은 카운터, 원인이 다르다) |
|
||||
| L4/UX-04 | 확인 | Low·P3 | `src/presentation/routes/app-router.tsx:81-97`: `loadingSurface`는 `data-surface` 속성에만 쓰인다. `LoadingSurface`(`src/presentation/components/async-surface.tsx:15-36`)에는 모양 인자가 없고, `.ui-skeleton` 블록 하나다(`primitives.css:125-127`). 매뉴얼은 "로딩 화면 이름"이라고 한다(`docs/manual/01-add-a-feature.md:438`). `global-ids.md:26`은 "검사 없음(형식만)"이다. fe-ux 체크리스트(`SKILL.md:51`)를 어긴다. routing 6.1·12절은 기록 설계서라 근거로 쓰지 않았다. 약속은 렌즈 문장이다 | `tests/component/router.test.tsx`: `loadingSurface`가 다른 두 라우트(collection·form)의 Suspense fallback DOM 구조가 서로 다른지 단언한다. 지금 실패한다 | **예.** 고치는 두 안 중 하나는 계약 `routes.*.loadingSurface`의 값 집합을 닫힌 union으로 바꾼다(FE-REG-ROUTE 기준선, 생성 명령 출력). 다른 하나는 렌즈와 매뉴얼의 약속을 거둔다 | — |
|
||||
| L4/UX-05 | 확인·등급 조정 | Low·P2 | `src/presentation/templates/page-templates.tsx:18-25`: `PageActionDefinition`에 `pending`이 없다. `:285-292`는 `disabled`를 쓴다. 라우터 `app-router.tsx:289-297`와 셸 `app-shell.tsx:95-111`이 `disabled={pending}`이다. `session-provider.tsx:92-107` `execute`에는 중복 실행 막기가 없다. 시험이 이 동작을 고정한다(`tests/component/route-status-surfaces.test.tsx:99`, `:119`). 약속은 이미 정한 `02-decision-tables.md:377`("꺼진 버튼은 키보드 포커스를 잃는다")과 DS 5.1 `:319`다. **반박 시도:** 6절 문장은 「저장 버튼」을 말한다. 그러나 이유 문장과 DS 5.1 "pending은 … disabled와 구분"이 세션 버튼에도 걸린다. 셸에 있어 모든 다운스트림의 모든 라우트가 복제한다. 그래서 P2로 올려 A11Y-03과 맞췄다 | `route-status-surfaces.test.tsx:99`·`:119`를 `not.toBeDisabled()` + `toHaveAttribute("aria-busy","true")` + 거절 뒤 `toHaveFocus()`로 바꾼다. 지금 실패한다 | 아니오. 선택 칸을 더하는 것뿐이라 기존 사용을 깨지 않는다 | **중복: L5/A11Y-03** |
|
||||
| L4/UX-06 | 확인·등급 조정(성격) | Low·P3, 구조적 위험 | `src/presentation/pages/home-page.tsx:50-55`, `:82-92`. CSS에 `ui-button--primary` 규칙이 없어(`primitives.css:14-71`) 지금은 `LinkButton`과 효과가 같다. 손 사본이 아직 같으므로 review-criteria 2절에 따라 구조적 위험이다. 홈은 개발자용 기본 화면이다(`PRODUCT.md:11`) | RED 없음. 바꾼 뒤 FE-GATE-008 visual의 `app-shell-wide-light` 차이로 확인한다 | 아니오 | 관련: L2 발견 근거 (2)(`page-templates.tsx`의 `LinkButton` 하위 경로 import) |
|
||||
| L4/UX-07 | 확인 | Low·P3 | `catalog.ts:153-154` 대 `:359-360`(en에 행동 문장이 없다). `:256` 대 `:322`(en은 마침표 하나 차이). `form-components.tsx:75`(`{label}: {message}`). **반박 시도:** 마침표 하나지만 fe-ux 체크리스트 "h1이 catalog 제목과 같다"를 그대로 어긴다. `tests/e2e/accessibility.spec.ts:91-92`는 ko catalog만 대조해서 en은 아무도 보지 않는다 | `tests/unit/i18n-contract.test.ts`: locale마다 `route.NOT_FOUND.title === page.notFound.title`. en에서 지금 실패한다 | 아니오 | — |
|
||||
| L4/DS-01 | 확인·등급 조정 | Low·P2 | **성립:** 규칙은 `src/presentation/AGENTS.md:9` "토큰 밖 색·간격을 쓰지 않는다"와 `docs/styling/design-tokens.md:9-10`이다. 증거는 다음과 같다. <br>- `shell.css`·`pages.css`·`templates.css`에 `var(--space-*)`가 0회다(grep). 예: `templates.css:4`, `:29`. <br>- 날 z-index: `shell.css:16`·`:47`, `responsive.css:19`. <br>- 날 그림자: `primitives.css:286`, `pages.css:159`. <br>- dialog가 `--radius-surface`를 쓴다(`primitives.css:409`). <br>- 필수 semantic 7개를 읽는 스타일이 0곳이다(grep. `semantic.css`의 정의만 있다). <br>**낮춘 이유:** 사용자 피해와 게이트 오답이 없다. fe-design-system 함정 1이 "리뷰가 잡는다"로 적은 영역이고, 리브랜드할 때만 드러난다. 3절의 Medium 예(위험 경로, 게이트 오답)와 모양이 다르다. <br>**줄 고침:** `--dialog-backdrop-weight`는 `component.css:14`다. **덧붙임:** `--layer-modal`을 아무도 읽지 않는 것은 native `<dialog>` top layer 때문이다(`dialog.tsx:61`) | `tests/unit/design-system-rules.test.ts`와 `scripts/check-design-system.ts:102-105`에 `unreadTokenFailures(REQUIRED_SEMANTIC_TOKENS, styles)`를 더한다. 지금 7건으로 실패한다. 날 길이 규칙은 `tests/fixtures/design-system/`에 거절 fixture와 통과 fixture를 함께 둔다 | 아니오. 검사를 올리는 쪽이다. 단 `REQUIRED_SEMANTIC_TOKENS`에서 `--layer-modal`을 빼는 안을 고르면 공개 상수가 바뀌므로 결정이 필요하다 | 부분 중복: L4/DS-05(가림막 비율), L4/DS-10(z-index 50·40) |
|
||||
| L4/DS-02 | 확인·등급 조정 | Low·P2, 구조적 위험 | **성립:** `bbde570`에는 `src/features/platform-examples-feature/contracts/platform-examples-contract.ts`의 `EXAMPLES_UI`·`EXAMPLES_STATES`가 public 등록 라우트였다. 그래서 `accessibility.spec.ts:35-96`의 라우트 순회가 두 화면을 검사했다. 지금 story axe는 둘뿐이다. `tests/storybook/galleries.spec.ts:58-72`는 `.ui-dialog`만, `tests/storybook/workshop.spec.ts:8-28`은 overlay story만 본다. `.storybook/preview.tsx:118-119`의 `a11y.test: "error"`는 돌릴 runner가 없다(`package.json:146-163`에 addon-vitest·test-runner가 없다). VD-08 결정 3(`docs/adr/VD-08-storybook-and-visual-evidence.md:37-38`)의 범위가 줄었다(T10). **낮춘 이유:** 지금 위반이 있다는 증거가 없다. 같은 T10 모양(1103/10-04 Low·P2, 1105/10-01 Low·P3)이 구조적 위험이었다. V4-X3에서 위반이 나오면 확인된 결함이다 | `tests/storybook/galleries.spec.ts`에 갤러리 두 story 전체 axe를 light·dark로 더한다. 검출력은 E-L5-02 변이(TextArea `id` 끊기)로 확인한다. 지금 위반이 있는지는 V4-X3 | 아니오 | **중복: L5/A11Y-04** |
|
||||
| L4/DS-03 | 확인·등급 조정 | Low·P3 | `src/presentation/design-system/index.ts`의 PascalCase 값 export 68개 가운데 43개가 `*.stories.tsx`에 없다(파일 대조. 토큰 상수 셋과 Portal·FocusRing·VisuallyHidden을 빼도 30개 이상). `galleries.stories.tsx:386`의 `AsyncSurface`는 refreshing 하나뿐이다. `preview.tsx`에 `globalTypes`가 없다. fe-design-system 체크리스트 "필수 story"(`SKILL.md:61`)를 어긴다. **낮춘 이유:** 골든·story 범위의 한계는 함정 11이 적은 알려진 범위다. `design-tokens.md:70-74`는 DS 설계의 목표 항목을 인수 시험 전에는 구현으로 보지 않는다고 적는다. 사용자 영향이 없다 | unit: `index.ts` 값 export마다 어느 story에 나오는지 대조한다(허용 목록: Portal·FocusRing·VisuallyHidden·토큰 상수). 지금 실패한다 | 아니오 | 관련: DS-02/A11Y-04(story가 없으면 story axe도 없다) |
|
||||
| L4/DS-04 | 확인 | Low·P2 | `playwright.visual.config.ts:41-51`에 `threshold`가 없어 기본값 0.2다. pixelmatch YIQ로 계산했다(허용 delta = 35215·t²). <br>- 0.2이면 허용 1408.6이다. <br>- 밝은 `--color-danger-surface`의 색상각 25→145는 sRGB (255,233,230)→(228,249,228)이고 delta 154.5다. <br>- 어두운 `--color-danger` red-500→600은 delta 1260.1이다. <br>- 둘 다 통과한다. 0.05(허용 88.0)이면 첫 변이가 걸린다. <br>약속은 VD-08 결정 8(`:47-48`)과 O-6("기록만 하지 않고 고친다")이다. 지금은 알려진 제한(`CHANGELOG.md:148`)만 있고 결정 대기 항목이 없다. 같은 모양인 1101/11-03이 Low·P2였다 | V4-X1(고친 값이 잡고, 깨끗한 빌드는 흔들리지 않는지 확인) | 아니오. 기준을 올리는 쪽이다 | — |
|
||||
| L4/DS-05 | 확인·등급 조정(성격) | Low·P3, 구조적 위험 | 세 토큰이 `component.css:14-24`에 있고 `REQUIRED_COMPONENT_TOKENS`(`token-contract.ts:46-56`)에는 없다. 검사는 그 목록만 본다(`check-design-system.ts:102-105`). 그런데 `design-tokens.md:16-17`·`:25`는 "모든 component 토큰"을 검사가 막는다고 적는다. 문서가 검사보다 넓다. **성격을 바꾼 이유:** `--dialog-backdrop`(`primitives.css:417`)과 `-on-surface`(`:435`)는 읽힌다. `-weight`는 `component.css` 안에서만 읽힌다. 지금 죽은 토큰은 없다. 계약에 그대로 넣으면 `-weight`가 UI-03에 걸린다. 그래서 DS-01의 `--opacity-scrim` 대체와 함께 고친다 | unit: `component.css`의 `--x:` 정의가 모두 `REQUIRED_COMPONENT_TOKENS`에 있다. 지금 3건으로 실패한다 | 아니오 | 부분 중복: DS-01 |
|
||||
| L4/DS-06 | 확인 | Low·P3 | 36개가 맞다. 줄 번호를 고친다: 밝은 테마 `semantic.css:17`·`:20-31`, 어두운 테마 `:59-65`·`:68-69`·`:71`·`:73`·`:76-87`. `design-tokens.md:3-7`("primitive.css에는 팔레트… semantic.css는 그것을 역할에 연결"), `PRODUCT.md:31`과 다르다 | unit: `semantic.css` 선언값에 `oklch(`가 0건이다(또는 문서의 예외 목록과 대조한다). 지금 36건으로 실패한다 | 아니오 | — |
|
||||
| L4/DS-07 | 확인 | Low·P3, 구조적 위험 | `src/presentation/design-system/primitives/button.tsx:8-14`는 `ButtonHTMLAttributes` 전체와 `className`을 받고 `:42-48`에서 그대로 넘긴다. `eslint.config.ts`에 style·className 규칙이 없다(grep 0). 근거는 렌즈 함정 7이다. DS 설계 `:322`·`:767`은 기록 설계서다. 템플릿에 기능이 0개라 지금 어긴 곳은 없다 | `check:types:fixtures`(`scripts/check-type-fixtures.ts`)에 `<Button style={{ color: "red" }} />` 거절 fixture를 둔다 | **예.** `style`을 공개 props에서 빼는 것은 디자인 시스템 배럴 표면의 BREAKING이다. JSDoc·문서로 범위만 적는 안은 결정이 필요 없다 | — |
|
||||
| L4/DS-08 | 확인 | Low·P3 | (1) `.claude/skills/fe-design-system/SKILL.md:35` "`in oklab`만"은 실제 규칙과 다르다. 규칙은 색상각 공간만 거절한다(`scripts/lib/design-system-rules.ts:62-71`). 코드는 `component.css:21`에서 `in srgb`를 일부러 쓴다(주석 `:8-13`). **범위 고침:** 리뷰어는 `design-tokens.md`가 규칙과 같다고 했지만, `design-tokens.md:23` "UI-02: `color-mix()`는 `oklab`에서 섞는다"도 같은 문장이다. 고칠 곳은 둘이다. (2) `SKILL.md:53`의 `--icon-size-*`는 없는 이름이다. 실제는 `--size-icon-*`다(`primitive.css:55-57`). `--icon-stroke-*`는 `--icon-stroke-default`(`:58`)와 맞으니 문제가 아니다 | `scripts/tests/test_claude_setup.py`: 스킬에 백틱으로 적은 `--토큰` 패턴이 토큰 CSS의 이름과 맞는지 본다. `--icon-size-*`에서 지금 실패한다 | 아니오 | — |
|
||||
| L4/DS-09 | 확인 | Low·P3 | `design-tokens.md:48-57`에 여섯 항목만 있다. `:70`은 "지금 구현된 … primitive 기준선을 적는다"고 한다. 실제 primitive는 25개가 넘는다(`index.ts`). **반박 시도:** 목록이 「전부」라고 말하지는 않는다. 그러나 절 제목과 `:70`이 지금 목록이라고 주장하고, `fe-a11y/SKILL.md:36`이 이 절을 근거로 든다. 낡은 문장(W1)이다 | RED 없음. 문서라 `verify:documentation`으로 본다 | 아니오 | — |
|
||||
| L4/DS-10 | 확인 | Low·P3 | `responsive.css:17-42`, `pages.css:219-221`. `data-open`이나 `app-shell__scrim`을 쓰는 TS·TSX가 0곳이다(grep). `.app-shell__sidebar`는 `app-shell.tsx:121`에서 쓰이니 `display: none`만 효과가 있다 | 선택: unit 「styles의 class 선택자는 TS·TSX 어딘가에 쓰인다」. 지금 `app-shell__scrim`으로 실패한다 | 아니오 | 부분 중복: DS-01(z-index 50·40) |
|
||||
| L5/A11Y-01 | 확인 | Medium·P2 | `scripts/verify-a11y-manual.ts:61-68`은 기록끼리 Release ID가 같은지만 본다. 후보 ID를 받는 입력이 없다(`:24`의 `--format-only`뿐). release 쪽 코드는 보고서를 읽지 않는다. `promotion-readiness.ts:26-28`은 게이트 ID만 본다. 약속은 `manual-checklist.md:3-4`("한 release 후보에 대해")와 `:11-12`("release 후보마다 한 번")이고, 이 모양은 결함 패턴 G7 「이전 release를 보고 통과」다. **반박 시도:** `:8-9` "맞지 않는 release ID"는 기록끼리의 불일치로 읽을 수 있어 코드와 맞는다. 그래도 `:11-12` 「후보마다」는 지켜지지 않는다. **P1이 아닌 이유:** 세 기록이 모두 pending이라 지금은 게이트가 맞게 실패한다 | `tests/unit/manual-a11y-evidence.test.ts`: 세 기록을 `r1`로 서명하고 후보를 `r2`로 주면 실패하기를 기대한다. 지금은 후보를 줄 입력이 없다. 확인은 E-L5-08 | **예.** 후보 ID를 무엇으로 줄지가 release job 설계다. workflow `RELEASE_ID`는 run마다 달라 미리 서명할 수 없다(`.gitea/workflows/quality-gates.yml:31`, w2-fe-2 파일) | — |
|
||||
| L5/A11Y-02 | 확인 | Low·P2 | `templates.css:7-9`는 `@layer components` 안이고(`:1`), `base.css:77-80`의 `:focus-visible`은 `@layer base` 안이다(`:1`). layer 순서로 components가 이긴다. 대상 h1은 `page-header.tsx:47`(`tabIndex=-1`, `data-route-heading`)이다. 다른 heading focus 표시 규칙은 없다. 약속은 DS 8.1 "focus indicator를 제거하지 않는다"(`:527`), fe-a11y 함정 6, M2(`manual-checklist.md:52`)다. **반박 시도:** WCAG 2.4.7은 키보드로 조작하는 UI에 걸린다. `tabIndex=-1` h1은 조작 대상이 아니라 WCAG 위반인지는 다툴 수 있다. 그래도 repo 자신의 금지 문장이 더 좁아서 결함이 성립한다. 지난 리뷰가 판정한 적이 없다 | E-L5-03 시험(`tests/e2e/accessibility.spec.ts` 끝): 키보드 Enter 뒤 h1의 `outlineStyle`이 `solid`다. 지금 실패할 것으로 예상한다 | 아니오 | — |
|
||||
| L5/A11Y-03 | 확인 | Low·P2 | UX-05와 같은 원인이다(`app-shell.tsx:95-111`, `app-router.tsx:289-298`, `page-templates.tsx:18-25`·`:271-272`·`:285-292`). **반박한 부분:** Pagination(`pagination.tsx:35-60`)은 경계라서 꺼지는 것이고 pending이 아니다. DS 5.1(`:319`)은 pending만 말한다. 제안으로만 남긴다 | UX-05와 같다 | 아니오 | **중복: L4/UX-05** |
|
||||
| L5/A11Y-04 | 확인 | Low·P2, 구조적 위험 | DS-02와 같다. 여기에 더해 `fe-a11y/SKILL.md:68` "story axe `tests/storybook/`"가 실제 범위보다 넓게 적혀 있다 | E-L5-02 변이와 새 시험. 등급은 V4-X3 | 아니오 | **중복: L4/DS-02** |
|
||||
| L5/A11Y-05 | 확인·등급 조정 | Low·P3, 구조적 위험 | axe 태그가 2.0·2.1까지다(`accessibility.spec.ts:13` 외 셋). 수동 칸은 M1~M7과 스크린 리더뿐이다(`scripts/lib/manual-a11y-evidence.ts:7-16`, `create-feature.ts:1598-1610`). 2.4.11·2.5.8을 볼 칸이 없다. **낮춘 이유:** 자동 검사의 한계는 fe-a11y 함정 1이 적어 둔 알려진 한계이고, 지금 위반이 있다는 증거가 없다. V4-X4에서 템플릿 라우트 위반이 나오면 P2다 | `tests/unit/manual-a11y-evidence.test.ts`: 2.4.11 칸이 없는 기록을 format 검사가 거부한다. 등급은 V4-X4 | **부분 예.** `wcag22aa` 태그를 더하는 것은 결정이 필요 없다(기준을 올린다). 기록 양식에 칸을 더하면 다운스트림의 기존 기록과 생성 명령 출력이 바뀐다. 다음 동기화에서 FE-GATE-009 format 검사가 실패한다 | — |
|
||||
| L5/A11Y-06 | 확인 | Low·P2 | 주석은 1.4.13을 주장한다(`tooltip.tsx:8-12`). 설명은 `pointer-events: none`이고, `.ui-tooltip:hover`·`:focus-within`일 때만 `opacity: 1`이다(`primitives.css:502-522`). CSS 명세상 `pointer-events: none` 요소는 hit-test 대상이 아니다. 그래서 포인터가 설명 위에 있으면 `.ui-tooltip:hover`가 풀린다. 틈 `calc(100% + var(--space-2))`도 hover를 끊는다. 템플릿 라우트의 소비자는 0이지만 PRODUCT의 WCAG 2.2 AA와 주석의 주장을 어긴다 | E-L5-06 시험(`tests/storybook/galleries.spec.ts`). 지금 실패할 것으로 예상한다 | 아니오 | — |
|
||||
| L5/A11Y-07 | 확인·등급 조정 | Low·P3 | `docs/accessibility/route-reviews/{APP_HOME,EXAMPLES_PLATFORM,NOT_FOUND}.md:13`은 M4를 n/a "no modal on this route"로 채웠다. 그런데 `app-shell.tsx:126-144`가 모든 셸 라우트에 modal `Drawer`를 둔다(`dialog.tsx:61` `showModal`). `manual-checklist.md:60-61`(dialog가 있는 route는 n/a 금지)을 어긴다. `:20-21`은 이 기록을 복사해 시작하라고 한다. **낮춘 이유:** drawer의 modal 여부와 포커스 복원은 e2e가 이미 본다(`tests/e2e/app-shell.spec.ts:30-43`, `:49` 이하). 서명 전에 리뷰어가 칸을 바꿀 수 있다 | `tests/unit/manual-a11y-evidence.test.ts`: 커밋된 기록의 M4가 n/a가 아니다. 지금 세 기록에서 실패한다 | 아니오 | — |
|
||||
| L5/A11Y-08 | 확인·등급 조정 | Low·P2 | `accessibility.spec.ts:130-137`은 `body`의 `animationDuration`을 `["0s","0.00001s","1e-05s"]`와 비교한다. 규칙(`responsive.css:86-95`)이 있으면 `*`가 `body`에도 걸려 `1e-05s`가 나온다. 없으면 초기값 `0s`가 나온다. 둘 다 통과한다. CSS 초기값으로 정해지는 결과라 실행 없이 성립한다. `APP_HOME.md:18`이 이 시험을 증거로 든다. **등급:** 같은 T2 모양인 1101/10-01이 Low·P2였다. L5의 P3에서 올리고, L3/T-01의 Medium에서 내린다 | 같은 시험이 `.ui-spinner`(`primitives.css:116`)를 보게 한다. 허용 목록에서 `0s`를 빼고, `animationIterationCount`가 `"1"`인지와 no-preference 대조를 더한다. RED는 E-L5-01(= L3 E-01) 변이 | 아니오 | **중복: L3/T-01** |
|
||||
| L5/A11Y-09 | 확인 | Low·P3 | `fe-a11y/SKILL.md:54`와 `fe-ux/SKILL.md:61`은 "오류 요약으로 포커스"라고 적었다. `fe-qa/SKILL.md:59`는 "첫 오류로"다. 코드는 첫 오류 필드다(`use-app-form.ts:158-163`, `:296`). DS 설계도 8.3 `:580`(summary)와 `:335`(first-invalid)가 서로 다르다. 손 사본이 이미 갈렸으니 확인된 결함이고, 맞는 쪽은 코드다 | RED 없음. 문서라 `scripts/verify.sh docs`로 본다 | 아니오 | — |
|
||||
| L5/A11Y-10 | 확인 | Low·P3 | `popover.tsx:53`의 `role="dialog"`에 이름이 없다. 시험도 이름 없이 찾는다(`tests/component/design-system-platform.test.tsx:322`). axe `aria-dialog-name`은 best-practice라 WCAG 태그 스캔 밖이다 | 같은 줄을 `getByRole("dialog", { name: "설명 열기" })`로 바꾼다. 지금 실패한다 | 아니오 | — |
|
||||
| L5/A11Y-11 | 확인 | Low·P3, 구조적 위험 | `dialog.tsx:111-116`의 `onKeyDown`은 모든 Escape에서 `onClose`를 부르고 `defaultPrevented`를 보지 않는다. `menu.tsx:100-104`는 `preventDefault`만 하고 전파는 막지 않는다. 포털이 없어 React 이벤트가 dialog까지 올라간다. `popover.tsx:27-34`와 `tooltip.tsx:16-24`는 document listener다. 템플릿 소비자는 0이다 | E-L5-07 시험(`design-system-platform.test.tsx`). jsdom에서도 React 이벤트 전파가 재현되니 지금 실패할 것으로 예상한다 | 아니오 | — |
|
||||
| L5/A11Y-12 | **반박(제안으로만 남김)** | — | Tab에서 닫히지 않는 것은 맞다(`menu.tsx:58-71`). 그러나 repo 약속은 DS 5.1 표 `:303` "roving focus, typeahead, Escape"이고, menu 안 Escape는 동작한다(`:100-104`). 키보드만으로 닫을 길도 있다(Shift+Tab → trigger에서 Enter, `:76-79`가 열림을 토글). L5 자신이 Tabs의 APG 차이를 같은 이유로 결함 아님으로 판정했다(L5 5절). 2.4.11 가림은 화면을 띄워야 아는 추측이다 | — | 아니오 | — |
|
||||
| L5/A11Y-13 | 확인 | Low·P3 | `search-field.tsx:25`는 `required`를 꺼내 `Field`(`:36-41`)에만 넘기고 `<input>`(`:43-52`)에는 넘기지 않는다. 기호만 있고 programmatic 상태가 없다. `checkbox.tsx:31-45`는 input에는 있고 기호가 없다. 약속은 fe-a11y 체크리스트 `SKILL.md:54`다 | `tests/component/ui-primitives.test.tsx`: `<SearchField required …/>`의 searchbox가 `toBeRequired()`다. 지금 실패한다 | 아니오 | — |
|
||||
| L5/A11Y-14 | 확인 | Low·P3, 구조적 위험 | `toast.tsx:130-136`의 닫기는 focus된 버튼째 항목을 지우고, 포커스를 돌려 둘 곳이 없다. 근거는 DS 설계 `:337`("focus policy")와 `:548`("닫은 뒤 … 안전한 대체 위치로 focus 복원")이다. 소비자는 gallery뿐이다 | `design-system-platform.test.tsx`: toast 둘 → 첫 닫기에서 Enter → 둘째 닫기 버튼이 `toHaveFocus()`. 지금 실패한다 | 아니오 | — |
|
||||
| L5/A11Y-15 | 확인 | Low·P3 | `home-page.tsx:56`: role 없는 `div`에 `aria-label`이 있다. ARIA 1.2는 generic role의 이름을 금지한다 | `tests/component/starter-pages.test.tsx`: `getByRole("group", { name: message("home.readiness") })`. 지금 실패한다 | 아니오 | 중복: L4 3절 넘김(ID 없음) |
|
||||
| L5/A11Y-16 | **실행 필요** | 확인되면 Low·P3 | 공개 분기(`accessibility.spec.ts:89-94`)는 h1만 기다린다. busy 0 대기는 보호 분기(`:69`)에만 있다. `src/presentation/examples/platform-overview-page.tsx:555-557`은 Suspense와 `LoadingSurface`(`aria-busy`)이고, `:446-449`의 `dl`도 `aria-busy`다. 스캔할 때 busy가 남는지는 읽기만으로 가를 수 없다 | V4-X2(= E-L5-05) | 아니오 | — |
|
||||
| L5/A11Y-17 | 확인 | Low·P3, 구조적 위험 | `text-area.tsx:66-72`: `<output>`은 HTML-AAM에서 암묵 role이 `status`(polite live)이고, 입력할 때마다 값이 바뀐다. textarea의 `aria-describedby`(`:51`)는 `Field`의 설명·오류뿐이고 카운터가 없다. 약속은 DS 8.1 `:531`과 fe-a11y 함정 9다. 실제로 몇 번 읽히는지는 스크린 리더로만 안다 | `ui-primitives.test.tsx`: 카운터가 `role="status"`가 아니고, textarea의 accessible description에 들어 있다. 지금 실패한다 | 아니오 | 관련: L4/UX-03(같은 카운터, 원인이 다르다) |
|
||||
| L5/A11Y-18 | 확인 | Low·P3 [w2-fe-2 파일] | `config/ci/gates.json:993-1002`·`:1990-1993`에는 APP_HOME·NOT_FOUND만 있다. 검사 범위는 레지스트리 전체로 세 라우트다(`manual-a11y-evidence.ts:3-5`). 생성 기능이 기록을 더해도 이 목록은 템플릿 파일을 고쳐야 늘어난다. review-criteria 2절의 생성 명령 약속과도 어긋난다 | ci 계약 unit: FE-GATE-028 `evidenceArtifactIds`가 레지스트리 라우트 기록을 모두 덮는다. 지금 EXAMPLES_PLATFORM에서 실패한다 | 아니오(w2-fe-2와 맞춰 고친다) | — |
|
||||
|
||||
### 최종 등급 모음(중복 합친 뒤 33건)
|
||||
|
||||
- Medium·P2 1건: A11Y-01
|
||||
- Low·P2 8건: UX-02, UX-05/A11Y-03, DS-01, DS-02/A11Y-04, DS-04, A11Y-02, A11Y-06, A11Y-08
|
||||
- Low·P3 22건: 나머지 확인 건
|
||||
- 판정 보류 1건: A11Y-16(실행 필요)
|
||||
- 반박 1건: A11Y-12
|
||||
|
||||
## 2. 실험 목록
|
||||
|
||||
판정을 가르려면 V4-X2가 꼭 필요하다. V4-X1·X3·X4는 고칠 값과 등급을 정하는 실험이다. 모두 desktop의 깨끗한 checkout에서 돌리고, 실험마다 작업 폴더를 되돌린다(O-11).
|
||||
|
||||
| ID | 대상 | 명령 | 변이 패치 | 기대 결과 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| V4-X1 | L4/DS-04 (= X-02 2·3단계) | `scripts/verify.sh script test:visual`, 세 번 | (1) `semantic.css:30` `--color-danger-surface: oklch(0.96 0.035 25)` → `145`, 그리고 `playwright.visual.config.ts`의 `maxDiffPixels: 50,` 아래에 `threshold: 0.05,`를 넣는다. (2) semantic 변이를 되돌리고 threshold 줄만 남겨 두 번 돈다 | (1) `state-surfaces-light` 실패. (2) 두 번 모두 통과, 깨끗한 빌드는 0 px. (1)이 통과하면 0.05로도 부족하다는 뜻이라 값을 다시 고른다 |
|
||||
| V4-X2 | L5/A11Y-16 (= E-L5-05) | `scripts/verify.sh exec -- corepack pnpm exec playwright test tests/e2e/accessibility.spec.ts --grep "examples/platform" --repeat-each 10` | `accessibility.spec.ts:92` 뒤에 `process.stdout.write(\`busy-at-scan ${await page.locator("[aria-busy='true']").count()}\n\`);` | 0이 아닌 값이 한 번이라도 나오면 확인(Low·P3), 30회 모두 0이면 반박 |
|
||||
| V4-X3 | L4/DS-02 = L5/A11Y-04 등급 (= X-01) | `scripts/verify.sh exec -- corepack pnpm exec playwright test -c playwright.storybook.config.ts tests/storybook/zz-probe-axe.spec.ts` | `r1-L4-ux-ds.md` 4절 X-01의 새 파일(갤러리 두 story와 DS story 둘, light·dark, WCAG 태그 axe). 끝나면 지운다 | 위반 0이면 구조적 위험 Low·P2 그대로. critical·serious가 있으면 확인된 결함으로 올리고 위반 목록을 fe-a11y로 넘긴다 |
|
||||
| V4-X4 | L5/A11Y-05 등급 (= E-L5-04) | `scripts/verify.sh script test:a11y` | `tests/e2e/accessibility.spec.ts:13` 배열에 `"wcag22aa"` 추가 | 템플릿 라우트에 `target-size` 등 위반이 있으면 Low·P2, 없으면 Low·P3 그대로 |
|
||||
|
||||
고칠 때 RED로 쓸 시험은 판정에 필요하지 않다. 원 리뷰 파일의 패치를 그대로 쓴다.
|
||||
|
||||
- A11Y-08: E-L5-01(= L3 E-01)
|
||||
- A11Y-02: E-L5-03
|
||||
- A11Y-06: E-L5-06
|
||||
- A11Y-11: E-L5-07
|
||||
- A11Y-01: E-L5-08
|
||||
- UX-02: X-04
|
||||
- X-03(DS-01의 죽은 토큰)은 grep으로 이미 확인해서 필요 없다.
|
||||
|
||||
## 3. 소유자 결정 필요
|
||||
|
||||
- **L4/UX-04:** `loadingSurface` 값을 닫힌 union으로 바꿔 동작에 잇는다(계약 `routes` 칸, FE-REG-ROUTE 기준선, 생성 명령 출력이 바뀐다). 다른 안은 렌즈 체크리스트와 매뉴얼의 약속을 거두는 것이다.
|
||||
- **L4/DS-07:** primitive 공개 props에서 `style`을 빼는 것은 디자인 시스템 배럴의 BREAKING이다. 범위 문장만 적는 안은 결정이 필요 없다.
|
||||
- **L5/A11Y-01:** FE-GATE-028이 대조할 release 후보 ID를 정해야 한다. workflow `RELEASE_ID`는 run마다 달라 쓸 수 없다. release job 설계와 w2-fe-2 파일(`.gitea/**`)이 걸린다.
|
||||
- **L5/A11Y-05의 일부:** 수동 기록 양식에 2.4.11·2.5.8 칸을 더하면 다운스트림의 기존 기록과 생성 명령 출력이 바뀐다.
|
||||
- **(조건부) L4/DS-01:** `--layer-modal`을 `REQUIRED_SEMANTIC_TOKENS`에서 빼는 안을 고를 때만 결정이 필요하다. 공개 토큰 계약 상수가 바뀐다.
|
||||
@@ -0,0 +1,358 @@
|
||||
# 성숙도 리뷰 — round9 확인 리뷰 (2026-11-12)
|
||||
|
||||
> 기준: design-docs `conventions/template-maturity-review-guide.md`, 절차 `docs/work/improve.md` 4.1절, 판정 `docs/work/reference/review-criteria.md`. 대상: `main` `5250ff95`(PR #22 병합). 라운드 ID 접두어는 `1112`(리뷰 날짜)이고, 발견 ID는 `1112/NN-MM`이다(NN = 아래 영역 번호). 이 라운드는 폴더 대신 `docs/reviews/2026-11-round9-*.md` 파일 묶음으로 둔다(맡긴 쪽 brief). 영역 기록은 서브에이전트 리뷰어가 썼고 원문 그대로 옮겼다(`2026-11-round9-01-*.md`~`15-*.md`). 이 문서는 총괄 세션(r9-fe)이 결과를 모은 것이다. 실행은 desktop checkout 하나에서 공유 잠금 아래 했다. 리뷰 중 코드는 고치지 않았다.
|
||||
>
|
||||
> 맡긴 쪽이 따로 물은 것(W1이 tech-log에서 본 preload 검사 후보)의 답은 3절에 있다. 수정 라운드는 16절(조치)에 이어 적는다.
|
||||
|
||||
## 0. 평가 전제 (가이드 0.1)
|
||||
|
||||
| 전제 | 기록 | 판정에 미치는 영향 |
|
||||
|---|---|---|
|
||||
| 사용 목적 | 프론트엔드 템플릿(reference implementation). 짝 백엔드 템플릿과 함께 desktop 서버에 서비스를 빨리 출시하는 시작점(`PRODUCT.md`) | 다운스트림이 그대로 복제하는 기본값·문서·생성 명령이 판정 대상이다 |
|
||||
| 사용자와 팀 | 작성자 1명 + AI 세션. 다운스트림 2개(tech-log, memento) | 템플릿 파일을 고쳐야 하는 지점은 동기화 비용이 된다 |
|
||||
| 지원 실행 형태 | 브라우저 SPA + 정적 호스팅 + 선택형 Service Worker. SSR 없음 | 서버 메모리 상태·다중 인스턴스 경쟁은 적용 제외. 탭 사이 경쟁은 적용 |
|
||||
| 데이터와 권한 | 세션(짝 백엔드 인증), 선택형 OPFS 개인 파일, 공개 캐시. 관리자·테넌트 기능 없음 | 로그아웃·계정 삭제 뒤 남는 데이터가 주된 피해 경로다 |
|
||||
| 규모 목표 | 기능 수 증가 축과 번들·lab 예산으로 판정. 2026-11-07에 참조 기능과 예제 화면을 지워 템플릿은 기능 0개다. 초기 JS 194,403 B(gzip)·17파일, 예산 206,848 B·32파일(이번 FE-GATE-012) | 기능 라우트는 생성 기능으로만 볼 수 있다 |
|
||||
| 의존 시스템 | 짝 백엔드(pin `45d2a478`, `config/contracts/backend-contract-pin.json`. 백엔드 main은 그 뒤 238커밋), 정적 호스팅(nginx 예시), Gitea Actions(runner 1대가 돈다. PR CI는 merge job 셋) | 짝 계약 어긋남과 runner 전제를 따로 본다 |
|
||||
| 운영 목표 | lab 예산(`config/performance/budgets.json`). RPO·RTO 없음 | 운영 복구 목표는 판정하지 않는다 |
|
||||
| 지원·비지원 | OPFS·realtime·SW·Web Push·업로드는 opt-in. bulk `results` 비지원. FE-GATE-013은 desktop 호스트의 user namespace 제약으로 실패하고, 뒤 명령이 모두 rc=0이면 merge 판정에서 뺀다(2026-11-12 결정, `docs/work/reference/gates.md` 3절) | 없는 기능을 결함으로 세지 않는다 |
|
||||
|
||||
## 1. 사용 결정 (36.5-1)
|
||||
|
||||
| 용도 | 결정 | 막는 항목 |
|
||||
|---|---|---|
|
||||
| 템플릿 상태 그대로 merge 게이트 통과 | 사용 가능 | 13/14 rc=0. FE-GATE-013은 결정된 호스트 제약 조건을 채운다(11.1절) |
|
||||
| `create:feature`로 기능을 더하고 템플릿 CI로 merge | **조건부 사용 가능** | 기능 ID를 `invoice`·`order`로 시작하게(또는 정확히 `invoice-feature`·`order-feature`로) 만들면 템플릿 시험의 사본 생성이 거부되어 FE-GATE-005·008이 실패한다(1112/08-02, P1). 그 밖의 ID는 통과한다(FE-GATE-020 scaffold 드릴) |
|
||||
| 다운스트림(tech-log·memento)에 정리 단계 묶음 전파 | 조건부 사용 가능 | 생성된 작성 페이지가 결과 불명 판정 사본을 가져 플랫폼 수정이 전파되지 않는다(1112/01-01). 이월 1106/14-02(해시 대조) 재발 |
|
||||
| 짝 백엔드에 붙는 쓰기 폼(NEVER·KEYED) | 조건부 사용 가능 | 다시 마운트한 폼의 재전송이 화면 값을 제출 값으로 쓴다(이월 1106/03-01 FR-03). 재전송의 쓰기 전 거절이 "입력 내용을 확인해 주세요." 아래에 나온다(1112/04-02) |
|
||||
| 짝 백엔드와 파일 업로드 | 조건부 사용 가능 | 업로드의 401이 세션에 닿지 않고, JWT 모드에서는 업로드에 세션 bearer를 붙일 지원 경로가 없다(1112/07-01). 이월 1105/01-02(백엔드 몫) |
|
||||
| 짝 백엔드 계약을 지금 백엔드 main과 맞춰 쓰기 | 조건부 사용 가능 | pin이 238커밋 뒤라 drift 검사가 실패할 상태다. 판정(code 집합·Envelope·멱등성 응답)은 같다(1112/02-05) |
|
||||
| release 단계(`RELEASE_READY`)까지 | 조건부 사용 가능 | FE-GATE-028이 지난 release에 서명한 수동 접근성 기록도 통과시킨다(1112/05-01). advisory 2건 결정 대기(D1) |
|
||||
| 셸·디자인 시스템·읽기 화면 | 사용 가능 | primitive 접근성 Low 여럿(05 영역), 날 간격·층 값이 토큰을 건너뜀(1112/04-08) |
|
||||
| opt-in realtime·OPFS·SW·Web Push | 조건부 사용 가능 | 지난 라운드와 같다. 이월 남음·일부가 있다(13절) |
|
||||
|
||||
## 2. 차단 항목 (36.5-3)
|
||||
|
||||
### 2.1 새 High — 없음
|
||||
|
||||
### 2.2 새 P1 — 1건
|
||||
|
||||
| ID | 내용 | 재확인 |
|
||||
|---|---|---|
|
||||
| 1112/08-02 | 템플릿 시험이 저장소 사본에 고정 ID로 기능을 만든다: `tests/unit/manual-code-blocks.test.ts`(매뉴얼 예시 `invoice-feature`, FE-GATE-005), `scripts/lib/generated-feature.ts`(`order-feature`, FE-GATE-008의 생성 기능 e2e·청크 복구·부팅 실패 spec). 사본에는 제품 기능이 들어 있고 `create:feature`는 같은 ID·같은 접두어를 거부한다(`scripts/create-feature.ts:213-224`). 그래서 그 이름의 기능을 만든 제품은 기능 코드와 상관없이 merge 게이트에서 막힌다. 매뉴얼 1단계가 바로 그 ID를 예시로 쓴다. 리뷰어는 Medium·P2로 냈고, 반박 검증이 "생성 명령으로 빠른 출시" 약속을 깨는 것이라 Medium·P1로 올렸다(`review-criteria.md` 3절) | 총괄이 `create-feature.ts:203-224`, `manual-code-blocks.test.ts:24,99`, `generated-feature.ts:23,54`를 직접 읽었다. desktop 실험 X-GD02·X-GD02b 결과는 11.4절 |
|
||||
|
||||
### 2.3 이월 항목 중 남은 큰 것
|
||||
|
||||
| ID | 지금 | 남은 부분의 등급 |
|
||||
|---|---|---|
|
||||
| 1103/13-03 (D1) | 결정 대기 | Medium·P1 그대로. 운영 high advisory 2건(react-router·zod). 초기 JS가 194,403 B로 줄어 zod 갱신(약 +7 KB)이 지금 예산 안에 든다(R9-D10) |
|
||||
| 1106/03-01 FR-03 | 남음 | Low·P3(1106 DR-03과 같은 모양). 1112/01-02와 같은 결함 |
|
||||
| 1105/15-04 | 재발 | Low·P2. 예제 화면을 지운 뒤 lab이 기능 라우트를 하나도 재지 않는다 |
|
||||
| 1106/14-02 | 재발 | Low·P3. 정리 PR 통합 커밋 본문이 원격에 없는 해시를 가리킨다 |
|
||||
| 1105/01-02 프론트 몫 | 일부 · 백엔드로 넘김 | Low·P3. Fileserver code 표가 pin 대조 밖 |
|
||||
|
||||
### 2.4 심각도 조정 (반박 검증)
|
||||
|
||||
리뷰어 제안과 다르게 매긴 것만 적는다. 근거는 검증 기록 `2026-11-round9-12-*.md`~`15-*.md`.
|
||||
|
||||
| ID | 리뷰어 | 최종 | 이유 |
|
||||
|---|---|---|---|
|
||||
| 1112/08-02 | Medium·P2 | Medium·P1 | "생성 명령으로 빠른 출시" 약속을 깨는 것은 P1(`review-criteria.md` 3절) |
|
||||
| 1112/02-01 | Low·P2 | Low·P3 | 노트북 훅 시험(`scripts/tests/test_hooks.py:50,108-115`)이 두 변이를 잡는다. CI 게이트에는 없다 |
|
||||
| 1112/02-05 | Low·P2 | Low·P3 | 계약 문서가 근거를 pin 커밋 기준이라 적고, drift exit 1은 설계된 신호다 |
|
||||
| 1112/08-03·08-04·08-05 | Low·P2 | Low·P3 | 뒤 단계가 원인 이름을 대며 멈춘다 / FE-GATE-005가 merge 전에 잡는다 / 위험이 결정 커밋 본문에 적혀 있다 |
|
||||
| 1112/03-01(=05-08) | Medium·P2 | Low·P2 | 구현된 규칙을 시험이 고정하지 못하는 같은 모양 1101/10-01이 Low·P2였다 |
|
||||
| 1112/06-01·06-02 | Medium·P2 | Low·P2 | 첫 진입 왕복 하나 / 빌드가 이름을 대고 실패할 뿐 사용자 피해가 없다. 실험(V3-X2)에서 lab 예산을 넘으면 06-01을 다시 올린다 |
|
||||
| 1112/04-08·04-09 | Medium·P2 | Low·P2 | 게이트 오답·사용자 피해가 없다 / 지금 위반 증거가 없는 구조적 위험 |
|
||||
| 1112/04-01·04-10·05-05·05-07 | P2 | P3 | 영향 범위가 좁다 |
|
||||
| 1112/04-05·05-08 | P3 | P2 | 같은 모양(1112/05-03, 1101/10-01)과 맞춤 |
|
||||
|
||||
### 2.5 합친 중복
|
||||
|
||||
| 센 ID | 같은 결함 | 이유 |
|
||||
|---|---|---|
|
||||
| 1112/05-03 | 1112/04-05 | 셸·상태 화면 버튼을 처리 중 `disabled`로 끈다 |
|
||||
| 1112/05-04 | 1112/04-09 | 갤러리를 story로 옮기며 전체 화면 axe 검사가 빠졌다 |
|
||||
| 1112/05-08 | 1112/03-01 | reduced-motion e2e가 규칙을 지워도 통과한다 |
|
||||
| 1106/03-01 FR-03(이월) | 1112/01-02 | 다시 마운트한 폼의 재전송 값 |
|
||||
| 1112/02-06 | 1112/08-17, 1112/09-02 | 2026-11-08 문서 이동 뒤 살아 있는 문서가 기록 문서(설계서)를 지금 동작의 정본으로 가리킨다 |
|
||||
| 1112/02-05 | 1112/08-18 | 짝 백엔드 pin과 문서의 백엔드 기준 차이 |
|
||||
| 1112/10-02 | 1112/08-14 | 결정 색인 빈틈(결정 대기 8행, FE-GATE-029 이전 결정) |
|
||||
|
||||
## 3. 맡긴 쪽이 물은 것 — W1의 preload 검사 후보
|
||||
|
||||
- 질문: W1이 tech-log에서 "`tests/support/browser/preload-use.ts`가 쓰이지 않는 preload를 검사하지 않고 WebKit preload 추측 경고만 받아들인다"고 적었다. 템플릿 결함인가?
|
||||
- 답: **템플릿 결함이 아니다.** 템플릿의 strict `page` fixture는 쓰이지 않은 preload를 세 엔진 모두에서 직접 실패시킨다(`tests/support/browser/preload-use.ts:190-202`, `strict-browser-test.ts:84`). WebKit의 추측 경고는 정확히 그 문장 하나만 무시한다(`strict-browser-test.ts:16-24`). 응답을 직접 채우는 CSP spec은 `fulfillBuildScript`로 표식을 넣는다(`tests/e2e/production-csp.spec.ts:30-41`). Service Worker가 제어하는 문서는 `preloadunverifiable:service-worker:`로 이름을 붙여 실패시키고 SW update spec만 허용한다. tech-log main에는 `preload-use.ts`가 없다. W1이 본 것은 tech-log가 이 템플릿 파일을 아직 옮기지 않은 상태다(03 영역 0절).
|
||||
- 템플릿 쪽에 남은 좁은 빈틈(새 발견으로 셈): 두 번째 탭·SW recovery 손 검사는 strict 검사 밖(1112/03-05), old-tab 시험의 A 탭 허용이 검사되지 않는 문서를 가리킴(1112/03-06).
|
||||
- tech-log로 옮길 때는 응답을 가로채는 CSP·SW 시험도 `fulfillBuildScript`를 써야 한다. 이것은 tech-log 몫이다.
|
||||
|
||||
## 4. 새 발견 건수 — 지난 라운드와 비교
|
||||
|
||||
| 라운드 | 대상 | 새 발견(중복 합친 뒤) | High | P1 | Medium | Low |
|
||||
|---|---|---|---|---|---|---|
|
||||
| 2026-11-06 (5라운드) | `bbde570` | 25 | 0 | 0 | 1 | 24 |
|
||||
| 2026-11-12 (round9) | `5250ff95` | 80 | 0 | 1 | 5 | 75 |
|
||||
|
||||
- 등급별: Medium·P1 1, Medium·P2 4, Low·P2 12, Low·P3 63(영역 10의 1건 포함). 성격·관점별은 15절 색인과 영역 문서.
|
||||
- 반박 검증에서 9건을 반박했고(제안으로만 남김), 1건은 실행 결과로 정한다(1112/05-16).
|
||||
- 숫자가 늘어난 이유(추론): ① 이번에 처음 쓴 렌즈가 셋이다(UX·디자인 시스템 17건, 접근성 18건, 성능·빌드 9건 — 이전 라운드는 adapter·계약 중심 16영역이었다). ② 2026-11-07~12에 큰 변경이 들어왔다(정리 3·4단계, CI 재편, 문서 이동·한국어, 참조 기능 삭제). 새 발견의 약 3분의 1이 그 변경 뒤의 낡은 문장·사본이다(08·02 영역). ③ "Low까지 모두 적는다"는 brief로 리뷰어가 Low를 줄이지 않았다.
|
||||
|
||||
## 5. 확인된 강점 (36.5-2)
|
||||
|
||||
- 결과 불명 쓰기의 재전송 입구(재전송 버튼, 같은 입력 재저장, 실행기 재시도, poll, 업로드)에 새로 열린 곳이 없다. NEVER는 같은 입력을 `UNKNOWN_EFFECT_PENDING`으로 막고 KEYED는 같은 키를 쓴다(01 영역).
|
||||
- 계층 방향·배럴 경계·kernel 셋·기능·context 경계 위반이 0이다. 규칙 31개를 직접 만든 import 그래프에 대 보았다(02 영역).
|
||||
- 번들 기록과 지금 빌드가 49 B 안에서 맞고(허용치 256 B), 예산 여유가 생성 기능 약 12개다(06 영역).
|
||||
- XSS·CSP·token 저장 금지·Cache Storage·오류 원문 노출이 렌즈 기준을 지킨다(07 영역).
|
||||
- 쓰이지 않은 preload를 엔진과 상관없이 실패시키는 검사가 있다(3절).
|
||||
|
||||
## 6. 반복되는 원인 (36.5-4)
|
||||
|
||||
1. **큰 이동 뒤의 손 사본.** 문서 이동(2026-11-08)과 참조 기능 삭제(2026-11-07) 뒤, 살아 있는 문서가 기록 문서를 정본으로 가리키거나(02-06) 지운 시험이 지키던 동작이 시험 없이 남았다(10-01). 결함 패턴 W3·T7과 같은 모양이다.
|
||||
2. **템플릿 시험이 제품 상태를 가정한다.** 고정 기능 ID(08-02), 매뉴얼 예시 이름. 템플릿 원래 상태에서만 돌린 시험이 제품에서 깨진다(`review-criteria.md` 2절 「헷갈리는 경우」 마지막 행).
|
||||
3. **검사가 규칙의 존재를 지키지 않는다.** kernel 규칙 fixture(02-01), reduced-motion 시험(05-08), 갤러리 axe(05-04), 시각 허용치(04-11), 디자인 토큰 계약(04-12)처럼 "검사는 있는데 그 검사를 꺼도 아무것도 실패하지 않는" 곳.
|
||||
4. **공통 primitive의 상호작용 결함.** Popover 이름, Dialog 안 Escape, Toast focus, Tooltip hover(05 영역). 페이지마다가 아니라 primitive에서 고칠 것이다.
|
||||
|
||||
## 7. 결정이 필요한 것
|
||||
|
||||
공유 노트 `r9-fe-fix-plan.md`(총괄에게 보냄)의 R9-D1~D12다. 각 행에 권하는 안과 버릴 안이 있다. 결정할 사람: 프론트 소유자(총괄 경유).
|
||||
|
||||
| 번호 | 관련 | 권하는 안 |
|
||||
|---|---|---|
|
||||
| R9-D1 | 1112/01-01 | `useAppForm`에 코디네이터의 결과 불명 상태를 받는 선택 옵션을 더하고(추가만), 생성 작성 페이지가 그것을 쓰게 생성기를 고친다 |
|
||||
| R9-D2 | 1112/07-01 | 템플릿 조립이 업로드 capability를 감싸 401을 V3와 같은 `onCredentialRejected`로 보낸다(추가만). JWT bearer는 제품 조합 계약에 선택 함수 하나 |
|
||||
| R9-D3 | 1112/02-02·02-03, 0929/12-03 | `.dependency-cruiser.json` 파일 단위 예외를 실제 쓰임으로 좁힌다(지금 위반 0) |
|
||||
| R9-D4 | 1112/02-05 | pin을 백엔드 main으로 옮기고 drift 5건을 대조한다 |
|
||||
| R9-D5 | 1112/04-04 | `loadingSurface` 계약은 그대로, 매뉴얼·렌즈 문장을 실제 동작에 맞춘다 |
|
||||
| R9-D6 | 1112/04-14 | primitive props는 그대로, `check:design-system`에 호출부의 날 색·간격 검사를 더한다 |
|
||||
| R9-D7 | 1112/05-01 | FE-GATE-028이 release 후보 ID와 기록 ID를 대조한다(workflow 쪽은 w2-fe-2와 맞춤) |
|
||||
| R9-D8 | 1112/04-11 | 시각 골든 허용치를 실험으로 흔들림 없는 값까지 낮춘다 |
|
||||
| R9-D9 | 1112/05-05 | axe `wcag22aa` 태그(결정 불요) + 수동 기록 양식에 2.4.11·2.5.8 칸 |
|
||||
| R9-D10 | 1106/15-01(D9), D1 | D1을 먼저: zod·react-router 갱신이 지금 예산 안에 드니 갱신하고, 드릴을 다시 재서 D9 규칙으로 예산을 정한다 |
|
||||
| R9-D11 | 1112/03-10 | 그대로 둔다(게이트마다 증거를 새로 만드는 계약). 결함 아님으로 닫는다 |
|
||||
| R9-D12 | 1101/15-03 | CSS·라우트 lazy 합은 기록만 하고 예산은 두지 않는다 |
|
||||
|
||||
## 8. 미검증 (36.5-5)
|
||||
|
||||
- 실제 Gitea runner에서의 결과: 이 리뷰는 desktop에 CI env를 준 실행만 했다(E2~E3, 실제 CI 미검증). 실행 환경 대기 항목은 runner로 확인해야 한다(11 영역).
|
||||
- 화면을 띄워야 아는 것: 세션 버튼 실패 뒤 focus 위치, sticky 폼 버튼과 toast가 focus를 가리는지(2.4.11), forced-colors 표시, 다크 테마 가림막(04·05 영역 1절).
|
||||
- FE-GATE-026(lab)과 release 단계: 돌리지 않았다.
|
||||
- 실험 결과로 정할 것: 1112/05-16(aria-busy), 1112/03-02(OPFS 미지원 엔진 여부 E-02).
|
||||
|
||||
## 9. 개선 순서 (36.5-6)
|
||||
|
||||
원인 묶음마다 PR 하나(공유 노트 `r9-fe-fix-plan.md` F1~F14). 순서: F1(P1) → 결정이 필요 없는 묶음(F2의 결정 밖 부분, F3, F4, F6, F8~F12) → 결정을 받은 묶음.
|
||||
|
||||
## 10. 재검토 조건 (36.5-7)
|
||||
|
||||
- 짝 백엔드 pin을 옮길 때(R9-D4): 계약 문서 6.1절 근거 경로와 drift 대조 전부.
|
||||
- 생성기 출력이 바뀔 때: 이미 생성한 기능으로 전파되지 않는 판정 사본(01-01).
|
||||
- 첫 공개 기능 라우트가 생길 때: lab 기능 라우트(1105/15-04)와 CSS·lazy 합 예산(R9-D12).
|
||||
|
||||
## 11. 리뷰 범위 (36.1)
|
||||
|
||||
### 11.1 게이트 실행 결과 (`5250ff95`, desktop, CI env, 공유 잠금)
|
||||
|
||||
| 실행 | 결과 | 로그 |
|
||||
|---|---|---|
|
||||
| `VERIFY_SNAPSHOT=1 scripts/verify.sh merge` | FE-GATE-001~012·020 rc=0, FE-GATE-013 rc=1(사전 점검: `bwrap: loopback: Failed RTM_NEWADDR`, `kernel.apparmor_restrict_unprivileged_userns = 1`) | desktop `/tmp/claude-gates/r9fe-base/` |
|
||||
| `scripts/verify.sh parts FE-GATE-013` | test:system rc=1(같은 사전 점검), 뒤 명령 넷(verify:reproducible-build·build:release-candidate·verify:local-evidence·check:browser-security) rc=0 | `/tmp/claude-gates/r9fe-base-013parts/` |
|
||||
| `scripts/verify.sh documentation` | FE-GATE-017 rc=0 | `/tmp/claude-gates/r9fe-base-docs/` |
|
||||
|
||||
FE-GATE-013은 `docs/work/reference/gates.md` 3절 두 조건(실패가 호스트 제약 하나뿐, 뒤 명령 모두 rc=0)을 채워 merge 판정에서 뺐다. 게이트 충족은 runner 통과로만 센다.
|
||||
|
||||
### 11.2 영역 분할
|
||||
|
||||
| NN | 영역(렌즈) | 영역 문서 | 렌즈 스킬 |
|
||||
|---|---|---|---|
|
||||
| 01 | React·데이터 흐름 + SRP | [01-react](2026-11-round9-01-react.md) | `fe-react` |
|
||||
| 02 | 구조·공통 계약(짝 백엔드 포함) + SRP | [02-structure-contracts](2026-11-round9-02-structure-contracts.md) | `fe-structure` |
|
||||
| 03 | 시험 환경·QA·시험 GWT | [03-testing-qa](2026-11-round9-03-testing-qa.md) | `fe-testing`, `fe-qa` |
|
||||
| 04 | UX·디자인 시스템 | [04-ux-design-system](2026-11-round9-04-ux-design-system.md) | `fe-ux`, `fe-design-system` |
|
||||
| 05 | 접근성 | [05-accessibility](2026-11-round9-05-accessibility.md) | `fe-a11y` |
|
||||
| 06 | 성능·빌드 비대화 | [06-performance-build](2026-11-round9-06-performance-build.md) | `fe-performance` |
|
||||
| 07 | 보안 | [07-security](2026-11-round9-07-security.md) | `fe-security` |
|
||||
| 08 | 가드레일·문서 정합·개발자 경험 | [08-guardrails-docs](2026-11-round9-08-guardrails-docs.md) | (규칙 `.claude/rules/`, `docs/work/reference/gates.md`) |
|
||||
| 09 | 나머지 adapter(업로드·OPFS·캐시·cross-context·realtime·push) | [09-adapters](2026-11-round9-09-adapters.md) | `fe-react`, `fe-security` |
|
||||
| 10 | 지난 발견 재판정 A(1106 01~09 영역) | [10-prior-findings-a](2026-11-round9-10-prior-findings-a.md) | 각 ID의 완료 기준 |
|
||||
| 11 | 지난 발견 재판정 B(1106 10~16 영역) | [11-prior-findings-b](2026-11-round9-11-prior-findings-b.md) | 같음 |
|
||||
|
||||
- 반박 검증: 새 눈 검증자 넷이 영역 01~09의 발견을 반박하려고 다시 읽었다([12](2026-11-round9-12-verify-react-adapters-security.md), [13](2026-11-round9-13-verify-structure-guardrails.md), [14](2026-11-round9-14-verify-testing-performance.md), [15](2026-11-round9-15-verify-ux-ds-a11y.md)). 영역 10·11의 새 발견 둘은 총괄이 읽었다.
|
||||
- 리뷰어와 검증자는 이 repo의 `reviewer` 정의(`.claude/agents/reviewer.md`)를 읽고 따르는 범용 서브에이전트다. 이 세션의 에이전트 목록에 `reviewer`가 없었다.
|
||||
- 리뷰어는 노트북에서 읽기만 했고, desktop은 위 로그 폴더를 읽기만 했다. 실험은 총괄이 모아 desktop에서 돌렸다(11.4절).
|
||||
|
||||
### 11.3 쓰지 않은 것
|
||||
|
||||
- 가이드 34.5절의 "변경·삭제·업데이트를 한 번 따라가기"는 FE-GATE-020 드릴(생성·제거·선택 기능 제거)의 이번 실행으로 대신했다.
|
||||
- 다운스트림 repo는 열지 않았다(03 영역이 tech-log main의 파일 유무만 봤다).
|
||||
|
||||
### 11.4 실험
|
||||
|
||||
| ID | 무엇 | 결과 |
|
||||
|---|---|---|
|
||||
| X-GD02 | 사본에 `invoice-feature`를 만든 뒤 `tests/unit/manual-code-blocks.test.ts` | (16절에 적는다) |
|
||||
| X-GD02b | 사본에 `order-feature`를 만든 뒤 `tests/e2e/generated-feature.spec.ts`(chromium) | (16절에 적는다) |
|
||||
|
||||
### 11.5 총괄 자신의 실수
|
||||
|
||||
- 결과 파일을 기다리는 감시 스크립트를 zsh에서 glob 없이 돌려 바로 실패했고, 다시 건 것은 빈 glob에서 `ls`가 작업 폴더를 세어 "모두 씀"으로 잘못 끝났다. 세 번째에 bash 배열로 셌다. 결과를 잘못 읽지는 않았다.
|
||||
|
||||
## 12. 28개 관점 판정 (36.2)
|
||||
|
||||
판정 규칙(총괄): 그 관점에 확인된 새 발견이 없으면 충족(이번 범위), High 이상이나 P1이 있으면 미충족, 그 밖이면 부분 충족. 평균하지 않는다. 이월 항목은 13절에서 따로 본다. 관점별 통제·증거는 영역 문서 4절이다.
|
||||
|
||||
| # | 관점 | 판정 | 확인된 새 발견(대표) |
|
||||
|---|---|---|---|
|
||||
| 1 | 코드 성숙도 | 부분 충족 | 1112/01-05, 1112/02-10, 1112/04-03, 1112/05-02, 1112/05-03, 1112/05-06 외 6건 |
|
||||
| 2 | 구조적 성숙도 | 부분 충족 | 1112/02-01, 1112/02-02, 1112/02-03 |
|
||||
| 3 | 변경 용이성 | 미충족 | 1112/01-01, 1112/04-01, 1112/04-08, 1112/04-13, 1112/08-02, 1112/08-08 |
|
||||
| 4 | 인지 부하 | 미충족 | 1112/01-01, 1112/02-06, 1112/02-07, 1112/04-04, 1112/04-06, 1112/04-15 외 3건 |
|
||||
| 5 | 위험 가시성 | 부분 충족 | 1112/01-01, 1112/01-05, 1112/03-02, 1112/05-01, 1112/05-05, 1112/05-07 |
|
||||
| 6 | 실패 성숙도 | 부분 충족 | 1112/01-03, 1112/01-04, 1112/01-06, 1112/04-02, 1112/05-03, 1112/07-01 |
|
||||
| 7 | 운영 성숙도 | 부분 충족 | 1112/05-01, 1112/05-18 |
|
||||
| 8 | 디버깅 가능성 | 부분 충족 | 1112/01-03, 1112/01-04, 1112/06-02, 1112/08-01, 1112/08-03, 1112/08-13 |
|
||||
| 9 | 유지보수 성숙도 | 부분 충족 | 1112/02-03, 1112/02-04, 1112/02-05, 1112/02-06, 1112/02-07, 1112/02-08 외 26건 |
|
||||
| 10 | 테스트 성숙도 | 미충족 | 1112/02-01, 1112/03-02, 1112/03-03, 1112/03-05, 1112/03-06, 1112/03-08 외 12건 |
|
||||
| 11 | 데이터 성숙도 | 충족(이번 범위에서 새 발견 없음) | |
|
||||
| 12 | 동시성 성숙도 | 부분 충족 | 1112/03-05 |
|
||||
| 13 | 확장성 | 부분 충족 | 1112/06-01, 1112/06-02 |
|
||||
| 14 | 성능 성숙도 | 부분 충족 | 1112/03-10, 1112/06-01, 1112/06-02, 1112/06-03, 1112/06-04, 1112/06-06 |
|
||||
| 15 | 보안 성숙도 | 부분 충족 | 1112/02-10, 1112/07-01, 1112/07-03 |
|
||||
| 16 | 의존성 성숙도 | 부분 충족 | 1112/06-09, 1112/07-02 |
|
||||
| 17 | API / Contract 성숙도 | 부분 충족 | 1112/01-06, 1112/02-05, 1112/03-09, 1112/07-01, 1112/09-01 |
|
||||
| 18 | 배포 성숙도 | 부분 충족 | 1112/06-03, 1112/06-04 |
|
||||
| 19 | 설정 성숙도 | 부분 충족 | 1112/08-03 |
|
||||
| 20 | 개발자 경험 | 미충족 | 1112/03-10, 1112/04-10, 1112/08-01, 1112/08-02, 1112/08-03, 1112/08-04 외 5건 |
|
||||
| 21 | Guardrail 성숙도 | 부분 충족 | 1112/02-01, 1112/02-02, 1112/02-03, 1112/02-04, 1112/02-05, 1112/03-02 외 22건 |
|
||||
| 22 | 추상화 성숙도 | 부분 충족 | 1112/01-01, 1112/01-06, 1112/02-02, 1112/02-10, 1112/04-04, 1112/04-08 외 4건 |
|
||||
| 23 | 일관성 | 부분 충족 | 1112/01-01, 1112/01-06, 1112/02-03, 1112/02-04, 1112/02-06, 1112/02-07 외 33건 |
|
||||
| 24 | 네이밍 / 의미 성숙도 | 부분 충족 | 1112/01-03, 1112/01-04, 1112/04-01, 1112/04-02, 1112/05-06, 1112/05-10 외 2건 |
|
||||
| 25 | 조직 확장성 | 부분 충족 | 1112/01-01, 1112/04-08 |
|
||||
| 26 | Ownership 성숙도 | 부분 충족 | 1112/02-05, 1112/05-07, 1112/08-14, 1112/08-15 |
|
||||
| 27 | 삭제 가능성 | 미충족 | 1112/05-04, 1112/08-02, 1112/08-08 |
|
||||
| 28 | 회복 가능성 | 부분 충족 | 1112/04-01, 1112/04-02, 1112/05-03, 1112/05-14 |
|
||||
|
||||
## 13. 지난 발견 상태 (2026-11-06 리뷰가 연 118행, `5250ff95`)
|
||||
|
||||
대상: 1106 README 13.4절에서 「고쳐짐」이 아닌 93행과, 1106의 새 발견 25건(+1103/15-02)의 16.4절 조치 상태. 판정은 영역 10·11 문서의 표가 정본이다(행마다 근거 `file:line`, 남은 것, 지금 등급, 고칠 방향).
|
||||
|
||||
| 묶음 | 행 | 고쳐짐 | 일부 | 남음 | 재발 | 해당 없음 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| A: 1106 01~09 영역 ([10](2026-11-round9-10-prior-findings-a.md)) | 58 | 18 | 17 | 23 | 0 | 0 |
|
||||
| B: 1106 10~16 영역 ([11](2026-11-round9-11-prior-findings-b.md)) | 60 | 15 | 18 | 23 | 2 | 2 |
|
||||
| 합계 | 118 | 33 | 35 | 46 | 2 | 2 |
|
||||
|
||||
- 붙은 표시: 결정 대기 20(그중 결정 색인 `docs/work/reference/decisions.md`에 있는 것은 D1·D2·D3·D6·D11의 5행뿐, 15행은 색인에 없다), 백엔드로 넘김 5, 실행 환경 대기·runner로 확인 10, D9 재검토 1.
|
||||
- 재발 2: 1105/15-04(lab이 기능 라우트를 재지 않음), 1106/14-02(정리 PR 통합 커밋 본문의 해시).
|
||||
- 결정 대기가 아닌 남음·일부·재발 60건이 고칠 대상이다(A 31, B 29). 목록은 영역 10의 「고칠 대상」, 영역 11의 7절.
|
||||
- 판정 정정: 1106/08-01은 「고침」에서 「일부」로 내렸다. 정리 2단계가 참조 기능 시험을 지우면서 다시 마운트한 폼의 시험(DR-03·FR-01)도 지웠다(1112/10-01).
|
||||
|
||||
## 14. 총괄 확인
|
||||
|
||||
- 1112/08-02(P1): 2.2절. 코드를 직접 읽었고, desktop 실험은 11.4절.
|
||||
- 영역 10·11이 낸 새 발견 둘:
|
||||
- 1112/10-01: `src/presentation/forms/use-app-form.ts:234-249`(다시 마운트한 폼의 분기)를 지키는 시험이 없다. `e3c8db48`이 `reference-page.test.tsx`를 지울 때 옮기지 않았다. Low·P3. 총괄이 `git show e3c8db48 --stat`과 `git grep -n remount -- tests`로 확인했다.
|
||||
- 1112/10-02: 결정 대기 15행(A 7, B 8)이 결정 색인에 없다(`decisions.md` 3절이 "형식을 채우지 못하면 결정 대기가 아니라 미완"이라 한다). Low·P3. 1112/08-14와 합친다.
|
||||
|
||||
## 15. 새 발견 색인
|
||||
|
||||
영역 01~09는 영역 문서의 이름표 순서로 번호를 붙였다. 「합침」 칸이 있는 행은 2.5절대로 다른 ID에서 센다. 「반박」 행은 결함으로 세지 않는다(제안으로만 남김). 최종 등급은 반박 검증 뒤의 값이다.
|
||||
|
||||
| 라운드 ID | 영역 문서 이름표 | 제목 | 반박 검증 | 최종 등급 | 소유자 결정 | 합침 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| 1112/01-01 | [R-01](2026-11-round9-01-react.md) | 결과 불명 화면의 판정이 코디네이터·폼·생성 페이지 사본 세 곳에 나뉘어 있다 | 확인 | Medium·P2 | 예 | |
|
||||
| 1112/01-02 | [R-02](2026-11-round9-01-react.md) | 재마운트한 폼에서 재전송하면 보낸 적 없는 화면 값을 제출 값으로 쓴다 | 확인 | Low·P3 | | 이월 1106/03-01 FR-03과 같은 결함(이월에서 센다) |
|
||||
| 1112/01-03 | [R-03](2026-11-round9-01-react.md) | 생성 기능의 입력이 scope fence로 끊긴 요청을 실패 telemetry로 보낸다 | 확인 | Low·P3 | | |
|
||||
| 1112/01-04 | [R-04](2026-11-round9-01-react.md) | query·mutation 실패 진단이 원인을 버린다 | 확인 | Low·P3 | | |
|
||||
| 1112/01-05 | [R-05](2026-11-round9-01-react.md) | `useApplicationQuery`가 파생 값(stale 실패)을 effect로 state에 복사하고, 다시 시도의 초기화가 바로 덮인다 | 확인 | Low·P3 | | |
|
||||
| 1112/01-06 | [R-06](2026-11-round9-01-react.md) | "모든 시도가 받는 거절" 판정이 기능 `mapProblem`이 바꿀 수 있는 `failure.code`를 읽는다 | 확인 | Low·P3 | | |
|
||||
| 1112/02-01 | [S-01](2026-11-round9-02-structure-contracts.md) | kernel 규칙(꼭 지킬 것 2)을 고정하는 회귀 fixture가 없다 | 확인 | Low·P3 | | |
|
||||
| 1112/02-02 | [S-02](2026-11-round9-02-structure-contracts.md) | 파일 단위 예외 둘이 실제 쓰임보다 넓어, presentation이 adapter에 닿는 길이 규칙 밖에 있다 | 확인 | Low·P3 | 예 | |
|
||||
| 1112/02-03 | [S-03](2026-11-round9-02-structure-contracts.md) | 파일 단위 예외 목록이 실제 쓰임과 이미 어긋났다 | 확인 | Low·P3 | | |
|
||||
| 1112/02-04 | [S-04](2026-11-round9-02-structure-contracts.md) | hand-rolled abort ratchet 상한이 실제보다 하나 크고, 머리 주석이 낡았다 | 확인 | Low·P3 | | |
|
||||
| 1112/02-05 | [S-05](2026-11-round9-02-structure-contracts.md) | 짝 계약 pin이 백엔드 main보다 238커밋 뒤이고, drift 검사가 실패할 상태다 | 확인 | Low·P3 | 예 | |
|
||||
| 1112/02-06 | [S-06](2026-11-round9-02-structure-contracts.md) | 현재 계약 문서 둘이 기록 문서(설계서)를 정본으로 삼고, 그 설계서는 다시 현재 문서를 정본이라 한다 | 확인 | Low·P3 | | |
|
||||
| 1112/02-07 | [S-07](2026-11-round9-02-structure-contracts.md) | 구조 정본을 가리키는 문장 넷이 낡았다 | 확인 | Low·P3 | | |
|
||||
| 1112/02-08 | [S-08](2026-11-round9-02-structure-contracts.md) | INVENTORY 머리·꼬리 문장이 표와 다르다 | 확인 | Low·P3 | | |
|
||||
| 1112/02-09 | [S-09](2026-11-round9-02-structure-contracts.md) | `check-adapter-inventory.ts`가 서로 무관한 검사 다섯을 한 스크립트에 둔다(SRP) | 반박 | — | | |
|
||||
| 1112/02-10 | [S-10](2026-11-round9-02-structure-contracts.md) | bootstrap이 "자격 증명 주인" 판정 순서를 두 함수에 따로 적는다(SRP·판정은 한 곳에) | 확인 | Low·P3 | | |
|
||||
| 1112/03-01 | [T-01](2026-11-round9-03-testing-qa.md) | 감소된 움직임 e2e가 규칙을 지워도 통과한다 | 확인 | Low·P3 | | 1112/05-08과 같은 결함(05-08에서 센다) |
|
||||
| 1112/03-02 | [T-02](2026-11-round9-03-testing-qa.md) | OPFS 05-01 브라우저 시험이 OPFS를 못 쓰면 단언 없이 통과하고, 증거는 "zero skipped"라 적는다 | 확인 | Low·P2 | 예 | |
|
||||
| 1112/03-03 | [T-03](2026-11-round9-03-testing-qa.md) | `check-test-evidence.ts`의 규칙 셋에 혼자 도는 거절 fixture가 없다 | 확인 | Low·P2 | | |
|
||||
| 1112/03-04 | [T-04](2026-11-round9-03-testing-qa.md) | strict fixture 강제가 `tests/e2e`의 문자열 포함 검사뿐이다 | 확인 | Low·P3 | | |
|
||||
| 1112/03-05 | [T-05](2026-11-round9-03-testing-qa.md) | 두 번째 탭과 자기 context는 strict 검사 밖이다 | 확인 | Low·P3 | | |
|
||||
| 1112/03-06 | [T-06](2026-11-round9-03-testing-qa.md) | old-tab 시험의 preload 허용 절반이 닿지 않는 문서를 가리키고, 주석이 fixture 동작과 다르다 | 확인 | Low·P3 | | |
|
||||
| 1112/03-07 | [T-07](2026-11-round9-03-testing-qa.md) | `ungated-tests.json`의 사유가 파일에 맞지 않는다 — 특히 순수 parser 시험 | 반박 | — | | |
|
||||
| 1112/03-08 | [T-08](2026-11-round9-03-testing-qa.md) | 새 timeout 규칙 밖에 손으로 정한 숫자 54곳과 옛 상수 4벌이 남았고, taxonomy가 옛 방식을 예로 든다 | 확인 | Low·P3 | | |
|
||||
| 1112/03-09 | [T-09](2026-11-round9-03-testing-qa.md) | 생성 기능 e2e의 오류 응답이 "짝 백엔드의 Envelope"라는 주석과 다르다 | 확인 | Low·P3 | | |
|
||||
| 1112/03-10 | [T-10](2026-11-round9-03-testing-qa.md) | `@a11y` 브라우저 시험을 merge가 두 번 돈다 | 확인 | Low·P3 | 예 | |
|
||||
| 1112/04-01 | [UX-01](2026-11-round9-04-ux-design-system.md) | 상태 화면 문구가 템플릿 개발자용이고, 행동을 말하면서 행동 버튼이 없다 | 확인 | Low·P3 | | |
|
||||
| 1112/04-02 | [UX-02](2026-11-round9-04-ux-design-system.md) | 입력과 무관한 저장 실패가 ErrorSummary "입력 내용을 확인해 주세요." 아래에 나온다 | 확인 | Low·P2 | | |
|
||||
| 1112/04-03 | [UX-03](2026-11-round9-04-ux-design-system.md) | 숫자를 locale formatter 없이 그린다 | 확인 | Low·P3 | | |
|
||||
| 1112/04-04 | [UX-04](2026-11-round9-04-ux-design-system.md) | 라우트 `loadingSurface`가 로딩 모양을 고르지 않는다 | 확인 | Low·P3 | 예 | |
|
||||
| 1112/04-05 | [UX-05](2026-11-round9-04-ux-design-system.md) | 진행 중 버튼을 `disabled`로 끄는 길이 템플릿 API에 남았다 | 확인 | Low·P2 | | 1112/05-03과 같은 결함(05-03에서 센다) |
|
||||
| 1112/04-06 | [UX-06](2026-11-round9-04-ux-design-system.md) | 홈이 페이지 템플릿과 `LinkButton`을 건너뛴다 | 확인 | Low·P3 | | |
|
||||
| 1112/04-07 | [UX-07](2026-11-round9-04-ux-design-system.md) | ko·en 문구 뜻이 다르고, 오류 요약 항목을 JSX 글자로 잇는다 | 확인 | Low·P3 | | |
|
||||
| 1112/04-08 | [DS-01](2026-11-round9-04-ux-design-system.md) | 스타일 파일이 간격·층·그림자·반경 토큰을 건너뛰고 날 값을 쓴다. 필수 semantic 토큰 7개는 아무 스타일도 읽지 않는다 | 확인 | Low·P2 | | |
|
||||
| 1112/04-09 | [DS-02](2026-11-round9-04-ux-design-system.md) | 갤러리를 story로 옮기면서 두 갤러리의 전체 화면 axe 검사를 잃었다 | 확인 | Low·P2 | | 1112/05-04와 같은 결함(05-04에서 센다) |
|
||||
| 1112/04-10 | [DS-03](2026-11-round9-04-ux-design-system.md) | 공개 배럴 컴포넌트 상당수에 story가 없고, 결과 불명 화면은 갤러리·골든에 없다 | 확인 | Low·P3 | | |
|
||||
| 1112/04-11 | [DS-04](2026-11-round9-04-ux-design-system.md) | 시각 골든의 색 허용치(기본 threshold 0.2)가 토큰 색 변경을 통과시킨다. 알려진 제한으로만 적혀 있다 | 확인 | Low·P2 | | |
|
||||
| 1112/04-12 | [DS-05](2026-11-round9-04-ux-design-system.md) | 1106/08-03이 더한 component 토큰 셋이 `token-contract.ts`에 없어 UI-03 검사 밖이다 | 확인 | Low·P3 | | |
|
||||
| 1112/04-13 | [DS-06](2026-11-round9-04-ux-design-system.md) | `semantic.css`가 팔레트를 거치지 않은 날 `oklch()` 36개를 정의한다 | 확인 | Low·P3 | | |
|
||||
| 1112/04-14 | [DS-07](2026-11-round9-04-ux-design-system.md) | primitive의 `className`·`style`이 범위 없이 열려 있다 | 확인 | Low·P3 | 예 | |
|
||||
| 1112/04-15 | [DS-08](2026-11-round9-04-ux-design-system.md) | fe-design-system 스킬의 기준 문장 두 곳이 실제 규칙·토큰과 다르다(범위 경로 밖, 렌즈 자체) | 확인 | Low·P3 | | |
|
||||
| 1112/04-16 | [DS-09](2026-11-round9-04-ux-design-system.md) | `docs/styling/design-tokens.md` 「들어 있는 primitive」가 지금 primitive의 일부만 적는다 | 확인 | Low·P3 | | |
|
||||
| 1112/04-17 | [DS-10](2026-11-round9-04-ux-design-system.md) | 지운 compact 사이드바의 CSS가 남았다. 두 번째 가림막(35%)과 날 z-index 50·40이 있다 | 확인 | Low·P3 | | |
|
||||
| 1112/05-01 | [A11Y-01](2026-11-round9-05-accessibility.md) | FE-GATE-028이 지난 release에 서명한 수동 기록을 새 release 후보에서도 통과시킨다 | 확인 | Medium·P2 | 예 | |
|
||||
| 1112/05-02 | [A11Y-02](2026-11-round9-05-accessibility.md) | 라우트 heading의 focus 표시를 키보드 사용자에게서도 지운다. M2를 모든 라우트에서 통과할 수 없다 | 확인 | Low·P2 | | |
|
||||
| 1112/05-03 | [A11Y-03](2026-11-round9-05-accessibility.md) | 셸 세션 버튼과 로그인 안내 버튼이 처리 중에 `disabled`가 되어 키보드 focus를 잃는다. 템플릿 action API에는 `pending`이 없다 | 확인 | Low·P2 | | |
|
||||
| 1112/05-04 | [A11Y-04](2026-11-round9-05-accessibility.md) | 예제 화면을 Storybook으로 옮기며 갤러리 전체 axe 검사가 빠졌다. 라우트에 없는 primitive 상태는 어느 게이트도 axe로 보지 않는다 | 확인 | Low·P2 | | |
|
||||
| 1112/05-05 | [A11Y-05](2026-11-round9-05-accessibility.md) | WCAG 2.2에서 새로 생긴 AA 기준은 자동 검사도 수동 checklist도 보지 않는다 | 확인 | Low·P3 | 예 | |
|
||||
| 1112/05-06 | [A11Y-06](2026-11-round9-05-accessibility.md) | Tooltip이 1.4.13 hoverable을 지키지 않는다. 포인터를 설명 위로 옮기면 사라진다 | 확인 | Low·P2 | | |
|
||||
| 1112/05-07 | [A11Y-07](2026-11-round9-05-accessibility.md) | 셸 modal drawer가 모든 라우트에 있는데 라우트 기록 셋이 M4를 "modal 없음"으로 채웠다. checklist는 그 기록을 복사해 시작하라고 한다 | 확인 | Low·P3 | | |
|
||||
| 1112/05-08 | [A11Y-08](2026-11-round9-05-accessibility.md) | reduced-motion e2e가 규칙을 지워도 통과한다 | 확인 | Low·P2 | | |
|
||||
| 1112/05-09 | [A11Y-09](2026-11-round9-05-accessibility.md) | fe-a11y·fe-ux 스킬은 제출 실패 때 오류 요약으로 focus가 간다고 적었다. 코드·시험·fe-qa는 첫 오류 필드다 | 확인 | Low·P3 | | |
|
||||
| 1112/05-10 | [A11Y-10](2026-11-round9-05-accessibility.md) | Popover가 이름 없는 `role="dialog"`를 그린다 | 확인 | Low·P3 | | |
|
||||
| 1112/05-11 | [A11Y-11](2026-11-round9-05-accessibility.md) | Dialog 안의 Menu·Popover·Tooltip에서 Escape를 누르면 Dialog까지 닫힌다 | 확인 | Low·P3 | | |
|
||||
| 1112/05-12 | [A11Y-12](2026-11-round9-05-accessibility.md) | Menu가 열린 채 Tab으로 focus가 빠져나간다. 그 뒤에는 Escape로 닫지 못한다 | 반박 | — | | |
|
||||
| 1112/05-13 | [A11Y-13](2026-11-round9-05-accessibility.md) | required 표시가 primitive마다 다르다. SearchField는 기호만 있고 Checkbox는 상태만 있다 | 확인 | Low·P3 | | |
|
||||
| 1112/05-14 | [A11Y-14](2026-11-round9-05-accessibility.md) | Toast 닫기 버튼으로 닫으면 focus가 `body`로 떨어진다. DS가 요구한 focus policy가 없다 | 확인 | Low·P3 | | |
|
||||
| 1112/05-15 | [A11Y-15](2026-11-round9-05-accessibility.md) | 홈의 `readiness-grid`가 role 없는 `div`에 `aria-label`을 단다 | 확인 | Low·P3 | | |
|
||||
| 1112/05-16 | [A11Y-16](2026-11-round9-05-accessibility.md) | 공개 라우트는 Suspense가 다 풀리기 전에 axe가 돌 수 있다. 그래도 `a11y.json`은 검사한 것으로 센다 | 실행 필요 | — | | |
|
||||
| 1112/05-17 | [A11Y-17](2026-11-round9-05-accessibility.md) | TextArea 글자 수 `<output>`이 글자를 칠 때마다 live region으로 발표된다 | 확인 | Low·P3 | | |
|
||||
| 1112/05-18 | [A11Y-18](2026-11-round9-05-accessibility.md) | FE-GATE-028 증거 목록이 라우트 기록을 손으로 골라 EXAMPLES_PLATFORM 기록이 빠졌다 | 확인 | Low·P3 | | |
|
||||
| 1112/06-01 | [PF-01](2026-11-round9-06-performance-build.md) | context 진입이 같은 context의 모든 기능 실행부를 받은 뒤에야 화면을 그린다 | 확인 | Low·P2 | | |
|
||||
| 1112/06-02 | [PF-02](2026-11-round9-06-performance-build.md) | Service Worker를 켜면 생성 기능 약 25개에서 빌드가 멈춘다. 규모 기록은 이 한계를 적지 않고, 실패 메시지는 개수를 말하지 않는다 | 확인 | Low·P2 | | |
|
||||
| 1112/06-03 | [PF-03](2026-11-round9-06-performance-build.md) | Tailwind가 docs·tests·scripts의 낱말로 유틸리티 35개를 만들어 render-blocking CSS에 싣는다 | 확인 | Low·P3 | | |
|
||||
| 1112/06-04 | [PF-04](2026-11-round9-06-performance-build.md) | build id만 바뀐 release가 초기 JS의 42.7%를 다시 받게 한다. 문서와 주석은 22%라고 적는다 | 확인 | Low·P3 | | |
|
||||
| 1112/06-05 | [PF-05](2026-11-round9-06-performance-build.md) | 꺼진 Service Worker의 페이지 컨트롤러 약 3.0 KB gzip이 초기 JS에 있다 | 반박 | — | | |
|
||||
| 1112/06-06 | [PF-06](2026-11-round9-06-performance-build.md) | 빌드 전용 schema가 초기 JS에 실려 boot 때 만들어진다 | 확인 | Low·P3 | | |
|
||||
| 1112/06-07 | [PF-07](2026-11-round9-06-performance-build.md) | HTML이 boot 그래프를 미리 받지 않아 첫 화면 앞에 왕복이 하나 더 있다 | 반박 | — | | |
|
||||
| 1112/06-08 | [PF-08](2026-11-round9-06-performance-build.md) | FE-GATE-008이 같은 Storybook을 두 번 빌드한다 | 반박 | — | | |
|
||||
| 1112/06-09 | [PF-09](2026-11-round9-06-performance-build.md) | 쓰지 않는 devDependency `dependency-cruiser` | 확인 | Low·P3 | | |
|
||||
| 1112/07-01 | [SEC-01](2026-11-round9-07-security.md) | 업로드 client의 서버 401이 세션에 닿지 않고, JWT 모드에는 업로드 자격 증명의 지원 경로가 없다 | 확인 | Medium·P2 | 예 | |
|
||||
| 1112/07-02 | [SEC-02](2026-11-round9-07-security.md) | `minimumReleaseAgeExclude`의 네 줄이 스스로 적은 재검토 조건을 넘겼다 | 확인 | Low·P3 | | |
|
||||
| 1112/07-03 | [SEC-03](2026-11-round9-07-security.md) | secret scan·공급망 목록의 "범위" 설명이 실제 검사 범위보다 좁다 | 확인 | Low·P3 | | |
|
||||
| 1112/08-01 | [GD-01](2026-11-round9-08-guardrails-docs.md) | `scripts/verify.sh parts`가 게이트 명령의 `args`를 버리고 음성 fixture의 진단 문구를 보지 않아, `ci:gate`와 다른 명령을 다른 기준으로 판정한다 | 확인 | Medium·P2 | | |
|
||||
| 1112/08-02 | [GD-02](2026-11-round9-08-guardrails-docs.md) | 매뉴얼 예시 ID `invoice-feature`와 e2e 고정 ID `order-feature`로 제품 기능을 만들면 FE-GATE-005·008이 실패하는데, `docs/manual/`은 그 ID를 1단계 예시로 쓰고 경고하지 않는다 | 확인 | Medium·P1 | | |
|
||||
| 1112/08-03 | [GD-03](2026-11-round9-08-guardrails-docs.md) | `test:system` 사전 점검이 provider 본 단계와 다른 방법으로 확인한다 — system bus를 보고 user manager·`systemd-run`·`prlimit`·위임 controller는 보지 않는다 | 확인 | Low·P3 | | |
|
||||
| 1112/08-04 | [GD-04](2026-11-round9-08-guardrails-docs.md) | 지침·작업 매뉴얼 문서의 검증 안내가 갈라졌고, 편집 훅 N5도 그 문서들을 노트북에서 끝나는 파일로 센다 | 확인 | Low·P3 | | |
|
||||
| 1112/08-05 | [GD-05](2026-11-round9-08-guardrails-docs.md) | 검사 script를 고칠 때의 규칙이 `merge`만 돌리라고 해서, main 단계로 옮긴 검사기 자기 시험(FE-GATE-029)이 PR 전에 돌지 않는다 | 확인 | Low·P3 | | |
|
||||
| 1112/08-06 | [GD-06](2026-11-round9-08-guardrails-docs.md) | `verify:documentation`의 명령 경로·script 검사가 이 repo의 주 진입점 `scripts/verify.sh …`와 `python3 …` 명령을 보지 않는다 | 확인 | Low·P3 | | |
|
||||
| 1112/08-07 | [GD-07](2026-11-round9-08-guardrails-docs.md) | 문서 검사 범위를 적은 손 사본 셋이 서로 다르다 | 확인 | Low·P3 | | |
|
||||
| 1112/08-08 | [GD-08](2026-11-round9-08-guardrails-docs.md) | `create:feature` 참조 문서가 초기 JS 기록 다시 쓰기를 빠뜨린다 — 머리 문장, 출력 예시, 되돌리기가 모두 | 확인 | Low·P3 | | |
|
||||
| 1112/08-09 | [GD-09](2026-11-round9-08-guardrails-docs.md) | 편집 훅 N5가 `verify.sh`를 읽거나 `--dry-run`만 해도 "desktop 실행"으로 세어 알림을 지운다 | 확인 | Low·P3 | | |
|
||||
| 1112/08-10 | [GD-10](2026-11-round9-08-guardrails-docs.md) | 경로별 규칙이 "편집 훅(N6)이 이 파일들의 편집을 알린다"고 하지만 N6은 그중 일부만 본다 | 확인 | Low·P3 | | |
|
||||
| 1112/08-11 | [GD-11](2026-11-round9-08-guardrails-docs.md) | `.claude/rules/tests.md`의 「돌리는 법」이 실행 위치의 정본(`operate.md` 4.1절)과 다르고, 적힌 그대로는 한 파일을 돌리지 못한다 | 확인 | Low·P3 | | |
|
||||
| 1112/08-12 | [GD-12](2026-11-round9-08-guardrails-docs.md) | 드릴 복사 목록의 위치를 `scripts/lib/removal-fixture.ts`로 적은 문서 여섯이 낡았다 — 목록은 `config/repository-layout.json`의 집합이다 | 반박 | — | | |
|
||||
| 1112/08-13 | [GD-13](2026-11-round9-08-guardrails-docs.md) | `ci:gate`의 실패 출력이 실패한 명령도, 원인이 남은 로그 경로도 말하지 않는다 | 확인 | Low·P3 | | |
|
||||
| 1112/08-14 | [GD-14](2026-11-round9-08-guardrails-docs.md) | 2026-11-07 소유자가 승인한 "검사기 자기 시험·gating 검사를 main 단계로, CI 계약 기준선 삭제" 결정이 결정 색인에 없다 | 확인 | Low·P3 | | |
|
||||
| 1112/08-15 | [GD-15](2026-11-round9-08-guardrails-docs.md) | 살아 있는 문서 아홉이 라운드 없는 리뷰 ID(`리뷰 12-05`)를 출처로 쓴다 | 확인 | Low·P3 | | |
|
||||
| 1112/08-16 | [GD-16](2026-11-round9-08-guardrails-docs.md) | `gates.md` 2절이 FE-GATE-012를 "merge에 더해" 돌리라고 쓴다 — FE-GATE-012는 merge 단계에 있다 | 확인 | Low·P3 | | |
|
||||
| 1112/08-17 | [GD-17](2026-11-round9-08-guardrails-docs.md) | 지금 동작(실행 격리 변수 표)을 설계 기록에서만 찾게 한다 | 확인 | Low·P3 | | 1112/02-06과 같은 원인(02-06에서 센다) |
|
||||
| 1112/08-18 | [GD-18](2026-11-round9-08-guardrails-docs.md) | 문서가 적은 짝 백엔드 기준이 pin과 다르다 | 확인 | Low·P3 | 예 | 1112/02-05와 같은 pin 차이(02-05에서 센다) |
|
||||
| 1112/08-19 | [GD-19](2026-11-round9-08-guardrails-docs.md) | 손으로 옮긴 숫자 두 곳(아직 같다) | 확인 | Low·P3 | | |
|
||||
| 1112/09-01 | [R-01](2026-11-round9-09-adapters.md) | 매뉴얼 02 §7 업로드 조립 예가 `declare module`로 capability를 보강한다. 매뉴얼 03과 recipe가 막는 방식이다 | 확인 | Low·P3 | | |
|
||||
| 1112/09-02 | [R-02](2026-11-round9-09-adapters.md) | 지금 규칙인 표 둘이 기록 문서(설계서)에만 있고, 살아 있는 문서와 코드 주석이 그 절을 정본처럼 가리킨다 | 확인 | Low·P3 | | 1112/02-06과 같은 원인(02-06에서 센다) |
|
||||
| 1112/09-03 | [R-03](2026-11-round9-09-adapters.md) | 계약 문서가 realtime에 "현재 concrete runtime은 없다"고 적는다. 같은 문서의 표, README, catalog는 참조 runtime이 있다고 적는다 | 반박 | — | | |
|
||||
| 1112/09-04 | [C-01](2026-11-round9-09-adapters.md) | 다른 탭의 reconcile과 승인 partition 삭제가 겹치는 경우를 지키는 시험이 없다 | 반박 | — | | || 1112/10-01 | [PA-01](2026-11-round9-10-prior-findings-a.md) | 다시 마운트한 폼의 분기를 지키는 시험이 참조 기능 삭제 때 사라졌다 | 총괄 확인 | Low·P3 | | |
|
||||
| 1112/10-02 | [PA-02](2026-11-round9-10-prior-findings-a.md) | 결정 대기 15행이 결정 색인에 없다 | 총괄 확인 | Low·P3 | | 1112/08-14와 합친다(08-14에서 센다) |
|
||||
@@ -4,7 +4,7 @@
|
||||
>
|
||||
> GOV-01. 이 표는 손으로 센 숫자가 아니라 `corepack pnpm check:adapter-inventory`가 `git ls-files src/adapters`와 정확히 대조하는 목록이다.
|
||||
>
|
||||
> `rg --files src/adapters | sort` 결과 119개를 하나씩 고정한 coverage ledger다. 책임·의존성·finding·유지/변경 판정은 연결된 상세 리뷰의 파일별 표를 따른다.
|
||||
> `rg --files src/adapters | sort` 결과를 하나씩 고정한 coverage ledger다(개수는 아래 합계 줄). 책임·의존성·finding·유지/변경 판정은 연결된 상세 리뷰의 파일별 표를 따른다.
|
||||
|
||||
| # | full path | 상세 리뷰 |
|
||||
| ---: | --- | --- |
|
||||
@@ -152,5 +152,5 @@
|
||||
| 142 | `src/adapters/AGENTS.md` | 계층 규칙 문서(코드 아님, 리뷰 대상 아님) |
|
||||
| 143 | `src/adapters/CLAUDE.md` | 위 문서를 가져오는 한 줄(`@AGENTS.md`) |
|
||||
|
||||
합계: **143/143**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다.
|
||||
합계: **143/143**. 새 adapter 파일이 추가되면 이 ledger를 같은 변경에서 갱신한다. 연결된 상세 리뷰는 그 리뷰 때의 기록이라 고치지 않는다. 상세 리뷰에 없는 파일은 그 행의 상세 리뷰 칸에 가장 가까운 묶음을 적는다.
|
||||
|
||||
|
||||
@@ -7,9 +7,15 @@ production source map.
|
||||
선언된 header 집합은 `config/hosting/security-headers.json`이다. hosting 검증은
|
||||
이 선언과 실제 응답을 비교한다. CSP는 일부러 `unsafe-inline`과 `unsafe-eval`을
|
||||
뺀다. production 코드와 빌드된 asset은 이 기준선에서도 동작해야 한다.
|
||||
`check:browser-security`(FE-GATE-013)는 선언한 CSP가 `'unsafe-inline'`,
|
||||
`'unsafe-eval'`, `*`, script의 scheme 통째 허용(`https:`)을 담으면 실패한다.
|
||||
브라우저처럼 같은 지시어가 두 번이면 앞의 것을 읽고, 키워드의 대소문자를 가리지
|
||||
않는다(`scripts/lib/csp-policy.ts`). hosting fixture
|
||||
(`tests/fixtures/hosting/response-headers.json`)는 이 header를 복사하지 않는다.
|
||||
fixture 모드는 선언을 그대로 답으로 쓰므로 CSP를 바꿀 때 선언 파일 하나만 고친다.
|
||||
`tests/e2e/production-csp.spec.ts`(`test:e2e`의 일부, FE-GATE-008)는 이 header로
|
||||
빌드를 서빙한다. 그리고 `securitypolicyviolation` 이벤트나 console 오류가 나면
|
||||
실패한다(리뷰 13-08). zod는 첫 object schema에서 `Function("")`을 시험 삼아
|
||||
실패한다(리뷰 0925/13-08). zod는 첫 object schema에서 `Function("")`을 시험 삼아
|
||||
실행한다. 그러면 정책이 부트할 때마다 이것을 위반으로 보고한다.
|
||||
`src/contracts/zod.ts`는 `jitless`를 켜서 이 시험을 건너뛴다. schema를 만드는
|
||||
모든 모듈은 `z`를 그 파일에서 import한다. 그래서 bundler가 chunk를 어떤 순서로
|
||||
|
||||
@@ -21,8 +21,9 @@
|
||||
- 새 직접 production 의존성에 대한 독립 리뷰
|
||||
- CycloneDX 1.6 SBOM, 그리고 inventory와의 component·edge 일치
|
||||
- source·lock·SBOM·dist를 묶은 local provenance 문서(statement)
|
||||
- secret scan. 대상은 source, 선택해서 켜는(opt-in) recipe, script, 테스트,
|
||||
추적되는 config/schema, public 폴더, 빌드된 asset, 생성된 release metadata다
|
||||
- secret scan. 대상은 추적되는 파일 전부(`git ls-files`, 문서와 `.env.example` 포함)와
|
||||
빌드된 `dist`, 생성된 `artifacts/release`다(`scripts/lib/repository-file-inventory.ts`).
|
||||
정책의 `trackedRoots`는 대상을 좁히지 않는다. 비어 있으면 안 되는 루트 목록이다
|
||||
- 두 번 빌드해 비교하는 `SOURCE_DATE_EPOCH` 재현성 검사
|
||||
|
||||
기준 명령은 다음과 같다.
|
||||
@@ -41,7 +42,7 @@ corepack pnpm check:supply-chain:fixtures
|
||||
|
||||
## 무엇을 증명하고 무엇을 증명하지 않는가
|
||||
|
||||
리뷰 13-12. 산출물마다 증명 범위가 다르다. 아래 "증명하지 못하는 것"을 증명된
|
||||
리뷰 0925/13-12. 산출물마다 증명 범위가 다르다. 아래 "증명하지 못하는 것"을 증명된
|
||||
것으로 읽지 않는다.
|
||||
|
||||
| 산출물 | 증명하는 것 | 증명하지 못하는 것 |
|
||||
@@ -64,7 +65,7 @@ corepack pnpm check:supply-chain:fixtures
|
||||
|
||||
## 최소 구성과 전체 구성
|
||||
|
||||
리뷰 13-13. 승격 단계까지 쓰려면 이 문서 아래의 runner 조건(bwrap, prlimit,
|
||||
리뷰 0925/13-13. 승격 단계까지 쓰려면 이 문서 아래의 runner 조건(bwrap, prlimit,
|
||||
systemd-run, systemd user manager 254 이상, cgroup v2 위임)과 오프라인 데이터로
|
||||
Ed25519 서명 보고서를 내는 provider 두 개가 필요하다. 이 repo는 그 환경에서
|
||||
workflow 전체를 한 번도 돌리지 않았다. 그래서 두 구성을 나눠 적는다.
|
||||
|
||||
@@ -109,8 +109,10 @@ host 수준 프로세스·sandbox 테스트를 Vitest를 쓴다는 이유만으
|
||||
- script 자신의 테스트는 명령줄 계약을 확인하려고 그 script, Node, Vitest를 짧게
|
||||
사는 자식 프로세스로 띄울 수 있다. 이런 테스트는 그 script의 다른 테스트 옆
|
||||
`tests/unit`에 그대로 둔다. 이런 suite는 전역 시간 제한을 올리지 않고 자기
|
||||
시간 제한을 더 길게 선언한다. 예를 들어 `tests/unit/risk-coverage.test.ts`는
|
||||
`PROCESS_HEAVY_TIMEOUT_MS`를 쓴다.
|
||||
시간 제한을 `childProcessTimeout(<desktop에서 잰 가장 긴 ms>)`
|
||||
(`tests/helpers/child-process-timeout.ts`)로 선언한다. 예를 들어
|
||||
`tests/unit/risk-coverage.test.ts`의 CLI 시험이 그렇다. 정하는 법과 검사는
|
||||
`docs/work/reference/testing.md` 2절이다.
|
||||
|
||||
end-to-end 시나리오와 자동 접근성 시나리오는 버전을 고정한 Chromium, Firefox,
|
||||
WebKit 엔진에서 돈다. responsive 계약은 320px reflow, 모바일 navigation drawer,
|
||||
|
||||
+1
-1
@@ -70,6 +70,6 @@
|
||||
|
||||
## 8. 이 폴더를 고칠 때
|
||||
|
||||
- 분량 상한: 지도(루트 `AGENTS.md`) 40줄, 루트 `CLAUDE.md` 15줄, 폴더 지역 규칙(`src/**/AGENTS.md`, 옆에 `@AGENTS.md` 한 줄 `CLAUDE.md`) 200줄, 이 README 80줄, playbook 150줄, 진입 경로(지도 + 루트 `CLAUDE.md` + README + playbook 하나) 350줄. `reference/`는 상한이 없다.
|
||||
- 분량 상한이 있다: 지도(루트 `AGENTS.md`), 루트 `CLAUDE.md`, 폴더 지역 규칙(`src/**/AGENTS.md`, 옆에 `@AGENTS.md` 한 줄 `CLAUDE.md`), 이 README, playbook, 진입 경로(지도 + 루트 `CLAUDE.md` + README + playbook 하나). 줄 수의 정본은 `scripts/check-work-docs.py`의 상수이고, 넘으면 그 검사가 상한과 함께 알린다. `reference/`는 상한이 없다.
|
||||
- 본문에 지난 리뷰 ID·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 [evidence.md](evidence.md)로 옮긴다. 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서도 같다. `reference/decisions.md`·`reference/defect-patterns.md`와 리뷰 문서는 ID를 둔다.
|
||||
- 고친 뒤 `scripts/verify.sh docs`(노트북)와 desktop `scripts/verify.sh script verify:documentation`이 통과해야 한다. 절차는 [docs-writing.md](docs-writing.md)다.
|
||||
|
||||
@@ -67,7 +67,7 @@
|
||||
| `src/adapters/{auth,http,storage}/**`, `src/presentation/security/**`, `config/security/**`, `config/hosting/security-headers.json`, `index.html`, `docs/security/**`, `recipes/session-owners/**` | fe-security | HTTP 실패 분류·재전송 → fe-react |
|
||||
| `package.json`, `pnpm-lock.yaml` | fe-security + fe-performance | 시험 도구만 바뀜 → fe-testing |
|
||||
| `config/ci/**`, `.gitea/**`, `scripts/**` | 지식 스킬 없음. `.claude/rules/gates-and-budgets.md`와 `desktop-gates` | 그 게이트가 지키는 분야의 렌즈 |
|
||||
| `docs/**/*.md`, `**/AGENTS.md`, `.claude/**/*.md` | 지식 스킬 없음. `.claude/rules/docs.md`, `scripts/verify.sh docs` | 문서가 설명하는 동작 → 그 분야 렌즈 |
|
||||
| `docs/**/*.md`, `**/AGENTS.md`, `.claude/**/*.md` | 지식 스킬 없음. `.claude/rules/docs.md`, `scripts/verify.sh docs`와 desktop `verify:documentation` | 문서가 설명하는 동작 → 그 분야 렌즈 |
|
||||
|
||||
## 4. 넘김 지도
|
||||
|
||||
|
||||
@@ -77,7 +77,7 @@
|
||||
### 4.4 수정 라운드와 묶음
|
||||
|
||||
- 통합 브랜치 `fix/maturity-review-<YYYY-MM-DD>`(리뷰 날짜)를 만들고, 영역별 수정은 각자 worktree의 브랜치에서 한다. 다른 수정에 기대는 묶음은 그 수정이 합쳐진 뒤 시작한다. CHANGELOG·문서는 마지막에 한 세션이 다시 쓴다.
|
||||
- 총괄이 브랜치를 `--no-ff`로 하나씩 합치고, 합칠 때마다 커밋 전 게이트를 돌린다. 합친 뒤에만 생긴 실패는 README 「통합에서 생긴 것」에 적는다. 합친 트리에서 merge 단계를 돌리고 회차별 결과를 표로 남긴다.
|
||||
- 총괄이 브랜치를 `--no-ff`로 하나씩 합치고, 합칠 때마다 커밋 전 게이트를 돌린다. 합친 뒤에만 생긴 실패는 README 「통합에서 생긴 것」에 적는다. 합친 트리에서 merge 단계를 돌리고 회차별 결과를 표로 남긴다. 통합에서 커밋을 다시 지었으면(fixup 접기, rebase) 커밋 본문과 CHANGELOG가 적은 해시를 `git merge-base --is-ancestor <해시> <브랜치 끝>`으로 하나씩 대조하고, 결과를 PR 본문 「검증」에 적는다. 리뷰 라운드가 아닌 정리·기능 통합도 같다.
|
||||
- 큰 라운드는 작은 PR로 나눈다. 자기완결적인 변경 하나에 PR 하나(대략 100줄, 1,000줄이면 너무 크다). 리팩터링과 동작 변경은 PR을 나눈다. 병합은 소유자가 한다. 라운드 사이에 새 기능이나 큰 구조 변경을 넣지 않는다(발견 수가 줄어드는지 볼 수 없다).
|
||||
|
||||
### 4.5 멈춤 기준 — 이 repo는 하나다
|
||||
|
||||
@@ -56,7 +56,7 @@
|
||||
- 생성 명령이 거부하면 `docs/manual/reference/errors.md`에서 메시지를 찾는다. 고칠 파일이 적혀 있다.
|
||||
- 짝 백엔드 응답 모양·오류 code가 문서와 다르면 코드(백엔드 생성기, 이 repo의 `src/adapters/http/backend-envelope.ts`)까지 따라가 사실을 적고 묻는다. 문서만 보고 판정 표를 정하지 않는다.
|
||||
- 기능 폴더 밖을 고쳐야만 되면 거기서 멈추고 [README](README.md) 5절 형식으로 묻는다.
|
||||
- brief가 매뉴얼 예시 이름(`invoice-feature` 등)을 기능 ID로 주면 그대로 만들지 말고 묻는다. 템플릿 시험(`tests/unit/manual-code-blocks.test.ts`)이 저장소 사본에 그 이름으로 기능을 만든다.
|
||||
- brief가 기능 ID를 `typecheck-probe-`로 시작하게 주면 그대로 만들지 말고 묻는다. 템플릿 시험이 저장소 사본에 만드는 예약 이름이다(`scripts/lib/template-probe-features.ts`). 매뉴얼 예시 이름(`invoice-feature`)은 써도 된다.
|
||||
|
||||
## 8. 보고 형식
|
||||
|
||||
|
||||
@@ -94,7 +94,7 @@
|
||||
|
||||
## 9. 자주 하는 실수
|
||||
|
||||
- 노트북 checkout에서 한 파일 테스트쯤은 괜찮다고 돌린다. 한 파일도 desktop에서 `scripts/verify.sh script`나 `ssh desktop`으로 돌린다.
|
||||
- 노트북 checkout에서 한 파일 테스트쯤은 괜찮다고 돌린다. 한 파일도 desktop에서 `scripts/verify.sh exec -- node scripts/run-vitest.ts run <파일>`로 돌린다(4.1절).
|
||||
- 한 테스트 파일을 `pnpm exec vitest run <file>`로 돌려 생성물이 없어 실패한다. `node scripts/run-vitest.ts run <file>`을 쓴다.
|
||||
- 캐시된 산출물(`dist/`, `artifacts/`)이 남은 checkout에서 돌려 다른 실행의 결과를 읽는다. `scripts/verify.sh`의 새 worktree를 쓴다.
|
||||
- 게이트 로그 대신 `ci:gate`의 마지막 줄만 옮긴다. `gate-artifacts/FE-GATE-0NN.txt`에서 숫자를 옮긴다.
|
||||
|
||||
@@ -57,6 +57,19 @@
|
||||
| 1105 결정 D7 | 2026-11-05 | 초기 JS 예산을 204,800 B에서 206,848 B로 올린다 | 1105 README 16.2절 |
|
||||
| 1106 결정 D9·D10 | 2026-11-06 | 초기 JS 예산 206,848 B를 그대로 두고 근거·되돌림 규칙을 `docs/operations/performance-evidence.md`에 둔다(D9). 결과 불명 KEYED 재전송이 쓰기 전 거절로 끝나도 훅이 결과 불명과 키를 지킨다. 재전송의 거절이 결과 불명을 푸는 것은 짝 백엔드 표의 code뿐이다(D10과 보완 둘, 판정 `src/contracts/errors.ts` `isRefusedOnEveryAttempt`) | 1106 README 16.2절 |
|
||||
| 결정 D8 FE-GATE-013 판정 | 2026-11-12 | desktop에서 FE-GATE-013의 실패가 사전 점검의 user namespace 제한(bwrap) 하나뿐이고 `scripts/verify.sh parts FE-GATE-013`의 뒤 명령이 모두 rc=0이면, merge 판정에서 그 실패를 호스트 원인으로 빼고 센다. 게이트 「충족」은 조건을 갖춘 runner에서 FE-GATE-013이 통과한 것으로만 센다. 버린 안: runner에서 통과할 때까지 merge 판정을 미충족으로 두기(그 runner가 아직 없어 모든 PR의 merge 판정이 막힌다). 재검토: 조건을 갖춘 runner가 merge 단계를 돌게 되면 desktop 예외가 아직 필요한지 다시 본다. 판정 방법은 `gates.md` 3절 | 소유자 결정 e(2026-11-11, 「그 조건이 되는 실행 환경을 찾아 초록으로」)에 따라 총괄이 권하는 안으로 정함(2026-11-12, repo 밖). 관련 발견 1105/12-01 |
|
||||
| 검사기 자기 시험의 단계 | 2026-11-07 | 검사기 자기 시험(`*:fixture` 15개)과 `check:ci:gating`을 merge에서 main 단계 FE-GATE-029로 옮기고, CI 계약 기준선 파일을 지운다. 버린 안: merge에 두기(PR마다 같은 자기 시험을 돈다). 위험: 검사기를 깨는 PR이 main에서야 빨개진다. 그래서 검사 script를 고치면 merge에 더해 FE-GATE-029를 돌린다(`.claude/rules/gates-and-budgets.md`) | 소유자 승인, 커밋 `f6b2b96c` 본문, `docs/operations/ci-quality-gates.md` 머리, round9 1112/08-14 |
|
||||
| round9 R9-D1 결과 불명 상태의 소유 | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). `useAppForm`이 코디네이터의 결과 불명 상태를 받는 선택 옵션을 갖고(추가만), 생성 작성 페이지가 그것을 쓴다. 이미 생성한 기능은 CHANGELOG 이행 안내. 버린 안: 문서로만 | round9 README 7절, 1112/01-01 |
|
||||
| round9 R9-D2 업로드 401 | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). 템플릿 조립이 업로드 capability를 감싸 401을 V3와 같은 `onCredentialRejected`로 보낸다(추가만). JWT bearer는 제품 조합 계약에 선택 함수 하나. 버린 안: 매뉴얼 문장만 | 같음, 1112/07-01 |
|
||||
| round9 R9-D3 파일 단위 예외 | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). `.dependency-cruiser.json`의 파일 단위 예외를 실제 쓰임으로 좁힌다(지금 위반 0). 버린 안: 그대로 | 같음, 1112/02-02·02-03, 0929/12-03 |
|
||||
| round9 R9-D4 짝 계약 pin | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). pin을 짝 백엔드 main으로 옮기고 drift 5건을 대조한다. 버린 안: 문서만 pin 기준으로 | 같음, 1112/02-05·08-18 |
|
||||
| round9 R9-D5 `loadingSurface` | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). 계약 값은 그대로, 매뉴얼·렌즈 문장을 실제 동작(로딩 모양을 고르지 않는 이름표)에 맞춘다. 버린 안: 닫힌 union으로 계약 변경 | 같음, 1112/04-04 |
|
||||
| round9 R9-D6 primitive `className`·`style` | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). 공개 props는 그대로 두고 `check:design-system`이 호출부의 날 색·간격을 잡는다(비파괴). 버린 안: `style` 제거(BREAKING) | 같음, 1112/04-14 |
|
||||
| round9 R9-D7 수동 접근성 후보 ID | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). FE-GATE-028이 기록의 Release ID를 release 후보 ID와 대조한다. workflow 쪽은 CI 세션이 맞춘다. 버린 안: 그대로 | 같음, 1112/05-01 |
|
||||
| round9 R9-D8 시각 골든 허용치 | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). 실험으로 흔들림 없는 값을 재서 낮춘다(검사 강화). 버린 안: 그대로 | 같음, 1112/04-11 |
|
||||
| round9 R9-D9 WCAG 2.2 | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). axe `wcag22aa` 태그를 더하고, 수동 기록 양식에 2.4.11·2.5.8 칸을 더한다(생성 출력이 바뀐다, CHANGELOG 안내). 버린 안: 태그만 | 같음, 1112/05-05 |
|
||||
| round9 R9-D10 예산과 advisory | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). D1을 먼저 정한다: zod·react-router 갱신이 지금 초기 JS 예산 안에 들어가므로 갱신하고, 드릴을 다시 재서 D9 규칙으로 예산을 정한다. 버린 안: 예산만 먼저 내림 | 같음, 1106/15-01, 1103/13-03 |
|
||||
| round9 R9-D11 `@a11y` 두 번 실행 | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). 그대로 둔다. 게이트마다 증거를 새로 만드는 계약이다. 결함 아님으로 닫는다. 버린 안: FE-GATE-009가 FE-GATE-008 결과를 쓰기 | 같음, 1112/03-10 |
|
||||
| round9 R9-D12 CSS·라우트 lazy 합 예산 | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). 지금 값을 기록만 하고 예산은 두지 않는다. 다시 볼 때: 첫 공개 기능 라우트 lab. 버린 안: 예산 신설 | 같음, 1101/15-03 |
|
||||
| 결정 p 선택 runtime 제거 드릴을 main 단계로 | 2026-11-12 | FE-GATE-020의 선택 runtime 제거 드릴 셋(optional recipe, browser file/storage, realtime)을 새 게이트 FE-GATE-030으로 떼어 main 단계(`main_gate`)에서 돌린다. 기능 드릴(샘플 제거, scaffold)은 merge에 남는다. 이유: runner PR 1회 약 30분 가운데 7분쯤이고, worker를 늘리지 않고 merge 25분 목표에 닿는 길이 이것뿐이었다. 대가: 그 셋의 회귀를 병합 뒤 main run에서 본다. main이 빨강이면 다음 PR이 고친다. 짝 백엔드가 무거운 lane을 nightly로 옮긴 것과 같은 모양이다. 재검토: runner가 늘거나 드릴이 빨라져 merge에 다시 넣어도 25분 안이면 되돌린다 | 소유자 결정 p(2026-11-12, design-docs `template-program/README.md` 5절, W2-FE의 O1 권하는 안 채택) |
|
||||
| 구조·기술 결정 기록 | 2026-07-26~ | `VD-01`~(빈 번호 있음) | `docs/adr/` |
|
||||
|
||||
@@ -77,15 +90,31 @@
|
||||
|
||||
### 3.1 지금 열린 결정 대기
|
||||
|
||||
2026-11-06 리뷰(1106) 시점이다. 다음 라운드가 닫거나 새로 열면 이 표를 고친다. D8은 2026-11-12에 정해 2.2절로 옮겼다.
|
||||
2026-11-12 리뷰(round9) 시점이다. 다음 라운드가 닫거나 새로 열면 이 표를 고친다. D8은 2026-11-12에 정해 2.2절로 옮겼다. 아래 「1106 이전 결정 대기」 행은 지난 리뷰들이 결정 대기로 남겼는데 이 색인에 없던 것이다(round9 1112/10-02). 각 행의 선택지와 권하는 안은 출처의 영역 문서에 있다.
|
||||
|
||||
| 번호 | 결정 | 관련 | 결정할 사람 | 출처 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| D1 | 운영 advisory 2건(zod·react-router). zod 갱신은 초기 JS를 약 7 KB 늘린다 | 1103/13-03 | 프론트 소유자 + reviewer | 1106 README 7절 |
|
||||
| D1 | 운영 advisory 2건(zod·react-router). zod 갱신은 초기 JS를 약 7 KB 늘린다. 2026-11-12 R9-D10(2.2절)으로 「갱신한다」로 정했다. 갱신이 들어가면 이 행을 지운다 | 1103/13-03 | 프론트 소유자 + reviewer | 1106 README 7절 |
|
||||
| D2 | 플랫폼 구성 화면을 진단 화면으로 인정할지, 기능으로 옮기고 다시 잴지 | 1103/09-04 | 프론트 소유자 | 같음 |
|
||||
| D3 | 백엔드 생성기의 목록 GET | 1103/03-07 | 두 repo 소유자 | 같음 |
|
||||
| D11 | 생성 기능 설치 상태의 브라우저 merge 게이트 | 1105/16-03 | 템플릿 담당 | 같음 |
|
||||
| D6(1105) | 실행 격리: 실행별 출력·빈 포트, 또는 "한 checkout 한 실행" 명시. `ci:gate` 두 실행은 아직 같은 `dist`·`artifacts/`를 쓴다 | 1105/12-04 | 프론트 소유자 | 1105 README 7절, 1106 README 2.3절 |
|
||||
| R9-D13 | 매뉴얼 02 7절 업로드 예: capability 타입을 `src/features/product-capabilities.ts`에 적으라는 규칙(매뉴얼 03)과, 그 파일이 `src/adapters/`를 import하지 못하는 규칙(`feature-and-app-roots-do-not-reach-adapters`)이 부딪친다. 권하는 안: `feature-adapter-contribution.ts`(이미 type-only 예외)가 adapter 의존 타입을 다시 내보내고 `product-capabilities.ts`가 그것을 쓴다 | 1112/09-01 | 프론트 소유자(총괄) | round9 README 7절, 공유 노트 `r9-fe-fix-plan.md` |
|
||||
| 1106 이전 결정 대기 | Service Worker 없는 빌드의 hosting probe 범위 | 1105/06-02 | 프론트 소유자 | 1106 README 13.4절, round9 영역 10 |
|
||||
| 같음 | 500 `IDEMPOTENCY_RECOVERY_REQUIRED` 뒤 재전송, 선언한 409를 필드 오류로 보일 때 VD-04 결정 5의 보완 | 1103/03-01 | 프론트 소유자 | 같음 |
|
||||
| 같음 | 캐시 `inspect()`의 signal과 "판정 불가"·"손상" 구분 | 0929/02-02 | 프론트 소유자 | 같음 |
|
||||
| 같음 | 파일 정책이 media type과 확장자 짝을 볼지 | 1101/02-02 | 프론트 소유자 | 같음 |
|
||||
| 같음 | `.dependency-cruiser.json`의 kernel 예외가 배럴 전체를 여는 것(쓰는 것은 `import type` 하나) | 0929/02-06 | 프론트 소유자 | 같음 |
|
||||
| 같음 | SSE EOF 분류 | 0929/04-02 | 프론트 소유자 | 같음 |
|
||||
| 같음 | SSE parser 동작이 설계 5.3·6.3과 다른 것 | 0929/04-03 | 프론트 소유자 | 같음 |
|
||||
| 같음 | 다운스트림(memento) 모양의 `check:registries`와 자리 없는 파일을 템플릿에 들일지 | 1103/14-02 | 두 repo 소유자 | 1106 README 13.4절, round9 영역 11 |
|
||||
| 같음 | 화면이 읽지 않는 라우트 `title`·`navigationLabel` 칸 정리 | 1103/16-06 | 프론트 소유자 | 같음 |
|
||||
| 같음 | 다운스트림이 찾은 템플릿 결함 후보를 받는 곳(이슈·FOLLOW-UP)과 상태 칸 | 0929/14-06 | 프론트 소유자 | 같음 |
|
||||
| 같음 | 도구·import 없는 unit 시험의 층(`tests/unit` 시간 대부분) | 1101/10-05 | 프론트 소유자 | 같음 |
|
||||
| 같음 | 한 merge에 `tests/unit`이 여러 번 도는 것 | 1101/10-06 | 프론트 소유자 | 같음 |
|
||||
| 같음 | 시험 helper 사본(`scopeSnapshot` 4벌, `as never`, `deferred()`)을 모을지 | 1101/10-08 | 프론트 소유자 | 같음 |
|
||||
| 같음 | ungated 목록에 owner·다시 볼 조건 칸을 둘지 | 0929/12-07 | 프론트 소유자 | 같음 |
|
||||
| 같음 | lab의 기능 라우트 진입 두 묶음(생성 라우트가 모두 `session-required`라 lab 대상이 못 된다) | 1105/15-04 | 프론트 소유자 | 같음 |
|
||||
|
||||
## 4. 커밋·PR
|
||||
|
||||
|
||||
@@ -37,7 +37,7 @@
|
||||
| T4 | 브라우저의 추정에 기댄다 | WebKit이 load 3초 뒤 한 번 하는 preload 추정에 기대 곧 쓰일 preload로 실패하고, 정말 안 쓴 preload는 놓친다 | 1103/11-09 | 추정 대신 확인하려는 사실을 직접 검사한다(`testing.md` 5절) | 10, 21 |
|
||||
| T5 | 그리는 중인 화면을 누른다 | 앱 뒤에 붙인 버튼이 렌더링 중 밀려 클릭이 닿지 않는다 | 1103/11-10 | 테스트가 붙이는 조작 요소는 고정 층에(`testing.md` 5절) | 10, 21 |
|
||||
| T6 | 테스트 대역이 실제 상대와 다르다 | 메모리 IndexedDB, fake, 백엔드 문서에서 옮긴 MSW 응답이 실제와 달라 결함을 숨긴다 | 0925/05-08, 0925/06-01, 1103/05-04, 1103/16-01, 1105/01-01 | 실제 짝 백엔드 응답으로 맞추기는 미조치(1105 README 9절) | 10, 17, 12 |
|
||||
| T7 | 플랫폼 테스트가 샘플·특정 파일·예시 이름에 묶인다 | 샘플을 지우면 테스트가 같이 사라지거나 게이트가 깨진다. 템플릿 테스트의 글자가 매뉴얼 예시 기능 이름과 부딪힌다 | 0925/14-01, 0929/10-02, 1101/16-02, 1105/10-01, 1105/16-04 | 테스트 전용 라우트와 플랫폼 소유 MSW 카탈로그(`testing.md` 2절). 탐침 이름은 예약 접두어 `typecheck-probe-*` | 27, 10, 21, 20 |
|
||||
| T7 | 플랫폼 테스트가 샘플·특정 파일·예시 이름에 묶인다 | 샘플을 지우면 테스트가 같이 사라지거나 게이트가 깨진다. 템플릿 테스트의 글자가 매뉴얼 예시 기능 이름과 부딪힌다 | 0925/14-01, 0929/10-02, 1101/16-02, 1105/10-01, 1105/16-04, 1112/08-02 | 테스트 전용 라우트와 플랫폼 소유 MSW 카탈로그(`testing.md` 2절). 템플릿 시험이 사본에 만드는 기능·탐침 이름은 예약 접두어 `typecheck-probe-*` | 27, 10, 21, 20 |
|
||||
| T8 | 빠른 계층에 느린 테스트가 섞인다 | unit에 프로세스를 띄우는 도구 테스트, 실제 시계로 기다리는 테스트가 섞이고 같은 파일을 두 번 돈다 | 1101/10-05, 1101/10-06, 1101/10-07, 1101/15-04 | 없음. `testing.md` 6절 | 14, 20, 10 |
|
||||
| T9 | 깨끗한 clone·다른 호스트에서 실패한다 | gitignore된 생성물, 기준선을 만든 CPU, 실행기가 넣는 npm 환경변수에 기댄다 | 0924 6.0절, 0925/10-01, 0925/11-03, 1101/15-05 | 한 파일 실행도 `scripts/run-vitest.ts`로. merge 판정은 깨끗한 checkout에서(`gates.md` 2·3절) | 10, 21, 20 |
|
||||
| T10 | 지우거나 바꾼 코드가 지키던 검사·테스트를 같이 잃는다 | 삭제·이름 변경이 실행 동작만 옮기고, 지운 행·테스트가 지키던 규칙은 옮기지 않는다 | 1103/07-01, 1103/10-04, 1105/04-01, 1105/10-01 | `structure.md` 9절 | 10, 21, 17 |
|
||||
|
||||
@@ -23,7 +23,7 @@ scripts/verify.sh <단계> [대상…] [--on here|<호스트>] [--log <이름>]
|
||||
| `docs` | 작업 매뉴얼 검사(`scripts/check-work-docs.py`)와 장부 형식 | 여기(노트북) |
|
||||
| `hooks` | repo 훅·검사기·장부 시험(`python3 -m unittest discover -s scripts/tests`) | 여기 |
|
||||
| `gate <ID>…` | 게이트마다 `corepack pnpm ci:gate <ID>`, CI env로 | desktop |
|
||||
| `parts <ID>` | 그 게이트의 명령(`commandIds`)을 하나씩 끝까지. 음성 fixture(`expect: fail`)는 정해진 종료 코드면 통과 | desktop |
|
||||
| `parts <ID>` | 그 게이트의 명령(`commandIds`)을 `args`와 함께 하나씩 끝까지. 음성 fixture(`expect: fail`)는 `ci:gate`처럼 정해진 종료 코드와 정해진 진단 문구(`expectedDiagnosticId`)가 둘 다 있어야 통과 | desktop |
|
||||
| `script <이름>… [-- 인자…]` | package script를 하나씩(예: `verify:documentation`). `--` 뒤 인자는 script가 하나일 때만 넘긴다(예: `scripts/verify.sh script test:sample-removal -- --feature=<id>`) | desktop |
|
||||
| `exec -- <명령…>` | 명령 하나. 한 테스트 파일(`node scripts/run-vitest.ts run <파일>`)이나 package script가 아닌 node 스크립트 | desktop |
|
||||
| stage id | `config/ci/gates.json` `stages`의 그 단계 `gateIds` 전부 | desktop |
|
||||
@@ -49,9 +49,10 @@ scripts/verify.sh <단계> [대상…] [--on here|<호스트>] [--log <이름>]
|
||||
| 브랜치를 합칠 때마다 | 커밋 전 8개. 합친 뒤에만 생긴 실패는 기록한다 |
|
||||
| merge 가능이라고 말하기 전 | `scripts/verify.sh merge`(3절) |
|
||||
| 리뷰 시작 | `scripts/verify.sh merge`와 `scripts/verify.sh documentation`(FE-GATE-017) |
|
||||
| 라우트 로딩·청크·초기 화면을 바꿀 때 | merge에 더해 `check:bundle`(FE-GATE-012)과 lab 게이트 `test:performance`(FE-GATE-026) |
|
||||
| 라우트 로딩·청크·초기 화면을 바꿀 때 | merge 단계(`check:bundle`의 FE-GATE-012 포함)에 더해 lab 게이트 `test:performance`(FE-GATE-026) |
|
||||
| 공급망·release 경로를 바꿀 때 | `scripts/verify.sh release` |
|
||||
| 작업 매뉴얼·훅을 바꿀 때 | 노트북 `scripts/verify.sh docs`, `scripts/verify.sh hooks` |
|
||||
| 작업 매뉴얼·훅을 바꿀 때 | 노트북 `scripts/verify.sh docs`, `scripts/verify.sh hooks`. 문서(작업 매뉴얼, `.claude/` 아래 문서, `AGENTS.md`·`CLAUDE.md` 포함)를 바꿨으면 desktop `scripts/verify.sh script verify:documentation`도 |
|
||||
| 검사 script·그 fixture를 바꿀 때 | merge에 더해 `scripts/verify.sh gate FE-GATE-029`(검사기 자기 시험은 main 단계에 있다) |
|
||||
|
||||
release 단계 게이트는 merge 단계에 없다. 그래서 lab 게이트 회귀가 147커밋 동안 아무 게이트에도 걸리지 않은 일이 있다. 바꾼 것이 release 단계 게이트가 지키는 것에 닿으면 그 게이트도 돌린다.
|
||||
|
||||
@@ -105,7 +106,7 @@ release 단계 게이트는 merge 단계에 없다. 그래서 lab 게이트 회
|
||||
|
||||
`verify:documentation`(FE-GATE-017, documentation 단계)이 문서를 검사하는 범위와 방법의 정본은 `scripts/verify-documentation-readiness.ts`, `scripts/lib/docs-system.ts`와 `docs/README.md` 5절이다.
|
||||
|
||||
- **범위:** 살아 있는 문서 전부(루트 `AGENTS.md`·`README.md`, `docs/` 아래 기록 밖 문서, `src/`의 `AGENTS.md`·모듈 README, `.claude/` 아래 문서). 기록(`docs/design/`, `docs/history/`, `docs/adr/`)은 머리 블록만 본다.
|
||||
- **범위:** 살아 있는 문서 전부(루트 `AGENTS.md`·`README.md`, `docs/` 아래 기록 밖 문서, `src/`의 `AGENTS.md`·모듈 README, `.claude/` 아래 문서). 기록(`docs/design/`, `docs/history/`)은 머리 블록만 보고, 결정 기록(`docs/adr/`)은 본문의 언어·문체도 본다.
|
||||
- **보는 것:** 언어(한국어인가), 문체(「~한다」), 숫자 복사, 기록의 머리 블록, 문서 지도와 루트 README 필수 절. 그리고 백틱 안의 repo 경로(`:줄` 꼬리는 떼고 본다), 셸 코드 블록과 백틱 안 명령의 경로 인자, 마크다운 링크, `corepack pnpm <script>`와 백틱 안 `<prefix>:<name>` 꼴의 package script, `FE-GATE-0NN` ID가 실제로 있는가. 설명·수치가 코드와 맞는지는 보지 않는다.
|
||||
- **예외:** git이 무시하는 생성 산출물, 복사한 프로젝트가 지운 작업 이력(루트 `README.md`의 지워도 되는 파일 표)은 없어도 된다.
|
||||
- **짝 백엔드 경로:** `config/contracts/backend-contract-pin.json`이 고정한 커밋의 트리에서 찾는다. 옆 checkout이 없거나 그 커밋이 없으면 실패가 아니라 "확인 못 함"으로 남긴다.
|
||||
|
||||
@@ -21,7 +21,7 @@ src/ 최상위 폴더 ── 역할: docs/architecture/layers.md 표
|
||||
| 규칙 예외의 이유·담당·재검토 조건 | 그 규칙의 `comment` | 사람이 본다 |
|
||||
| adapter 그룹의 공개 경계 | 규칙 `adapter-groups-are-reached-through-their-barrel` | `check:architecture`, 고정 fixture `tests/fixtures/architecture/dependency-graph/barrel` |
|
||||
| adapter 파일 목록 | `docs/reviews/adapters/INVENTORY.md` | `check:adapter-inventory`(FE-GATE-010) |
|
||||
| 공유 타입·프리미티브를 어디에 둘지 | `docs/architecture/contract-ownership.md` 「Decision rule」 | 사람이 본다 |
|
||||
| 공유 타입·프리미티브를 어디에 둘지 | `docs/architecture/contract-ownership.md` 「판단 규칙」 | 사람이 본다 |
|
||||
| 기능 폴더의 모양 | `docs/manual/01-add-a-feature.md`, `create:feature`가 만드는 파일 | FE-GATE-020의 `test:feature-scaffold` |
|
||||
| 재시도 의미, 결과 불명, 인증, 업로드의 판단 기준 | `docs/manual/02-decision-tables.md` | 사람이 본다 |
|
||||
| 오류·재시도·실패 경계·trace 모델 | `docs/architecture/scale-architecture.md`(코드 주석의 `scale-architecture.md §N`) | 사람이 본다 |
|
||||
@@ -84,7 +84,7 @@ src/ 최상위 폴더 ── 역할: docs/architecture/layers.md 표
|
||||
|
||||
- **repo 안:** 스키마 메타, 레지스트리 행, 허용 키 목록, 빌드 입력 목록, 저장 키를 원본(zod 스키마, descriptor, registry)에서 뽑는다. 손으로 다시 적어야 하면 원본과 대조하는 테스트를 같이 둔다. 두 검사기가 같은 산출물을 다른 키 목록으로 읽어 merge 게이트가 항상 실패한 일이 있다(결함 패턴 S1).
|
||||
- **이미 갈라진 복사본은 하나로 합친다.** 갈라진 recipe port는 지우고 `src` port를 다시 내보낸다.
|
||||
- **두 템플릿 사이:** 짝 백엔드의 프로토콜·오류 code·응답 모양·생성기 규칙을 옮길 때는 백엔드 문서만 보지 않고 **코드까지 따라간다**(백엔드 생성기, 프론트 폼까지). 판정 표를 백엔드 계약 문서만으로 정해 High를 만든 일이 있다. 옮긴 사실은 기준 커밋(`config/contracts/backend-contract-pin.json`)과 대조 테스트로 묶는다. pin과 drift 검사는 아직 계약 문서 글자만 비교하고, 답 표 JSON과 생성기 사실은 대조 밖이다(결함 패턴 S2).
|
||||
- **두 템플릿 사이:** 짝 백엔드의 프로토콜·오류 code·응답 모양·생성기 규칙을 옮길 때는 백엔드 문서만 보지 않고 **코드까지 따라간다**(백엔드 생성기, 프론트 폼까지). 판정 표를 백엔드 계약 문서만으로 정해 High를 만든 일이 있다. 옮긴 사실은 기준 커밋(`config/contracts/backend-contract-pin.json`)과 대조 테스트로 묶는다. drift 검사(`check:backend-contract-drift`)는 계약 문서 글자, 답 표 JSON(pin 사본과), 생성기 원본 파일이 pin 뒤에 바뀌었는지를 본다. 옮긴 사실의 내용 자체는 대조하지 않는다(결함 패턴 S2).
|
||||
- 짝 백엔드 repo는 읽기만 한다. 백엔드가 바꿔야 할 것은 "백엔드에 넘길 것"으로 적는다.
|
||||
|
||||
## 9. 코드 기준 — 지우거나 바꿀 때
|
||||
|
||||
@@ -38,8 +38,9 @@
|
||||
|
||||
- 스크립트 테스트가 자식 프로세스를 띄우면 그 suite가 자기 timeout을 선언한다. 전역 timeout을 올리지 않는다.
|
||||
- 값은 desktop에서 잰 가장 긴 실행으로 정한다: `childProcessTimeout(<ms>)`(`tests/helpers/child-process-timeout.ts`). 부하가 높은 desktop에서 자식 프로세스 테스트가 평소보다 몇 배 느려진 실측을 근거로 둔다.
|
||||
- 기본값보다 긴 timeout은 시험·describe·hook 모두 이 helper로만 준다. 자식 프로세스를 띄우지 않는 긴 시험(scale tier의 부하 시험 등)도 같다. 손으로 쓴 숫자(`60_000`)나 숫자 상수(`PROCESS_HEAVY_TIMEOUT_MS = 30_000`)는 `tests/unit/test-timeout-declarations.test.ts`가 파일과 줄로 거절한다. 여러 시험이 같은 값을 쓰면 파일 위에 `const X = childProcessTimeout(<그 시험들 중 가장 긴 ms>)`로 둔다.
|
||||
- 기본 timeout인 테스트가 자식 프로세스를 띄우면 `tests/setup.ts`가 그 호출에서 실패시킨다. helper나 import한 스크립트가 띄워도 같다. hook(`beforeAll` 등)은 보지 않는다.
|
||||
- 플랫폼을 지키는 테스트는 기능·스타터 화면에 묶지 않는다. 테스트 전용 라우트와 플랫폼 소유 MSW 카탈로그(`tests/mocks/`)를 쓴다(결함 패턴 T7). 생성물 탐침 이름은 예약 접두어(`typecheck-probe-*`)를 쓴다.
|
||||
- 플랫폼을 지키는 테스트는 기능·스타터 화면에 묶지 않는다. 테스트 전용 라우트와 플랫폼 소유 MSW 카탈로그(`tests/mocks/`)를 쓴다(결함 패턴 T7). 템플릿 시험이 저장소 사본에 만드는 기능과 생성물 탐침의 이름은 예약 접두어(`typecheck-probe-*`, `scripts/lib/template-probe-features.ts`)를 쓴다. 사본에는 제품 기능이 들어 있어, 흔한 업무 이름이나 매뉴얼 예시 이름을 쓰면 그 이름의 기능을 만든 제품에서 생성 명령이 거부한다.
|
||||
- 기능 테스트가 지워도 되는 문서를 읽으면 제거 드릴이 깨진다([structure.md](structure.md) 4절).
|
||||
- 테스트 작성의 편집 직후 규칙은 `.claude/rules/tests.md`다(Claude Code는 테스트 파일을 열 때 읽는다).
|
||||
|
||||
|
||||
@@ -6,13 +6,3 @@ saveExact: true
|
||||
allowBuilds:
|
||||
esbuild: true
|
||||
msw: true
|
||||
# 12-07. These exact pins were added on 2026-07-25 (946cf40, f3e105f) while
|
||||
# they were younger than pnpm's minimum release age. An exclusion covers that
|
||||
# exact version only, so a later version is checked again. Owner:
|
||||
# frontend-platform. Revisit: remove an entry when its version is bumped or is
|
||||
# older than the configured minimum release age.
|
||||
minimumReleaseAgeExclude:
|
||||
- '@playwright/test@1.62.0'
|
||||
- playwright-core@1.62.0
|
||||
- playwright@1.62.0
|
||||
- eslint@10.8.0
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
import { readdir } from "node:fs/promises";
|
||||
import { readdir, readFile } from "node:fs/promises";
|
||||
import { spawnSync } from "node:child_process";
|
||||
|
||||
import { declaredCspProblems } from "./lib/csp-policy.ts";
|
||||
|
||||
function requiredPnpmCli(): string {
|
||||
const executable = process.env.npm_execpath;
|
||||
if (!executable) {
|
||||
@@ -35,15 +37,28 @@ const forbidden = runPnpm([
|
||||
const distFiles = await readdir("dist", { recursive: true });
|
||||
const publicSourceMaps = distFiles.filter((file) => String(file).endsWith(".map"));
|
||||
|
||||
if (allowed.status !== 0 || forbidden.status === 0 || publicSourceMaps.length > 0) {
|
||||
const SECURITY_HEADERS = "config/hosting/security-headers.json";
|
||||
const cspProblems = declaredCspProblems(await readFile(SECURITY_HEADERS, "utf8"));
|
||||
|
||||
if (
|
||||
allowed.status !== 0 ||
|
||||
forbidden.status === 0 ||
|
||||
publicSourceMaps.length > 0 ||
|
||||
cspProblems.length > 0
|
||||
) {
|
||||
process.stderr.write(allowed.stderr || allowed.stdout);
|
||||
process.stderr.write(forbidden.stderr || forbidden.stdout);
|
||||
if (publicSourceMaps.length > 0) {
|
||||
process.stderr.write(`Public source maps found: ${publicSourceMaps.join(", ")}\n`);
|
||||
}
|
||||
if (cspProblems.length > 0) {
|
||||
process.stderr.write(
|
||||
`${SECURITY_HEADERS} Content-Security-Policy: ${cspProblems.join("; ")}\n`,
|
||||
);
|
||||
}
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
process.stdout.write(
|
||||
"Browser security fixtures: injection rejected, public source maps absent\n",
|
||||
"Browser security fixtures: injection rejected, public source maps absent, declared CSP allows no unsafe source\n",
|
||||
);
|
||||
|
||||
@@ -5,6 +5,7 @@ import { loadCiGateContract } from "./contracts/ci-gates.ts";
|
||||
import { loadProductCiOverlay } from "./contracts/product-ci-overlay.ts";
|
||||
import {
|
||||
gatedTestPaths,
|
||||
gatedTestTargets,
|
||||
listTestFiles,
|
||||
parseUngatedTestExclusions,
|
||||
ungatedTestFailures,
|
||||
@@ -38,7 +39,7 @@ try {
|
||||
failures.push(
|
||||
...ungatedTestFailures({
|
||||
testFiles: await listTestFiles(process.cwd()),
|
||||
gatedPaths: gatedTestPaths(
|
||||
gatedPaths: gatedTestTargets(
|
||||
packageScripts,
|
||||
[...contract.commands.map(({ script }) => script), ...productGateScripts],
|
||||
(file) => readFileSync(file, "utf8"),
|
||||
|
||||
@@ -1,10 +1,12 @@
|
||||
import {
|
||||
checkDeclaredCspFixtures,
|
||||
checkNonmatchingSecurityIncludeFixture,
|
||||
checkSecurityFixtures,
|
||||
} from "./lib/security-fixture-check.ts";
|
||||
|
||||
await checkNonmatchingSecurityIncludeFixture();
|
||||
await checkSecurityFixtures();
|
||||
await checkDeclaredCspFixtures();
|
||||
process.stdout.write(
|
||||
"Security fixtures: unmatched include rejected; 3 forbidden files detected\n",
|
||||
"Security fixtures: unmatched include rejected; 3 forbidden files detected; unsafe CSP fixture rejected\n",
|
||||
);
|
||||
|
||||
@@ -88,14 +88,24 @@ export async function findSystemTestPrerequisiteFailures(
|
||||
}
|
||||
|
||||
if (executable.get(BWRAP)) {
|
||||
const probe = host.spawn(BWRAP, NAMESPACE_PROBE_ARGUMENTS, PROBE_TIMEOUT_MS);
|
||||
if (probe.error || probe.status !== 0) {
|
||||
failures.push(await namespaceFailure(host, probe));
|
||||
}
|
||||
const failure = await findProviderSandboxNamespaceFailure(host);
|
||||
if (failure !== undefined) failures.push(failure);
|
||||
}
|
||||
return failures;
|
||||
}
|
||||
|
||||
/**
|
||||
* 1101/13-03. Whether this host lets the provider sandbox create its
|
||||
* namespaces, and if not, why and what to do. The release provider jobs run
|
||||
* it before the provider (scripts/run-and-validate-provider.ts).
|
||||
*/
|
||||
export async function findProviderSandboxNamespaceFailure(
|
||||
host: SystemTestHost = nodeSystemTestHost,
|
||||
): Promise<string | undefined> {
|
||||
const probe = host.spawn(BWRAP, NAMESPACE_PROBE_ARGUMENTS, PROBE_TIMEOUT_MS);
|
||||
return probe.error || probe.status !== 0 ? namespaceFailure(host, probe) : undefined;
|
||||
}
|
||||
|
||||
async function namespaceFailure(
|
||||
host: SystemTestHost,
|
||||
probe: ReturnType<SystemTestHost["spawn"]>,
|
||||
|
||||
@@ -432,6 +432,9 @@ const jobSchema = z
|
||||
browserGateIds: z.array(id).max(64),
|
||||
environment: z.array(environmentBindingSchema).max(32),
|
||||
steps: z.array(jobStepSchema).min(1).max(64),
|
||||
// 1101/13-03. What the runner of a job without a gate needs (the provider
|
||||
// jobs' sandbox). Rendered beside its runner label like a gate's.
|
||||
hostRequirements: z.array(nonEmpty.max(512)).min(1).max(8).optional(),
|
||||
})
|
||||
.strict();
|
||||
|
||||
@@ -862,6 +865,20 @@ function validateContractSemantics(
|
||||
// paired backend's nightly lanes.
|
||||
main_gate: ["FE-GATE-029", "FE-GATE-030"],
|
||||
};
|
||||
// 1101/13-03. The provider jobs run FE-GATE-013's sandbox (systemd-run
|
||||
// scope, bwrap with the same namespace options), so they need its host.
|
||||
const sandboxRequirements = JSON.stringify(
|
||||
contract.gates.find(({ id: gateId }) => gateId === "FE-GATE-013")?.hostRequirements ?? [],
|
||||
);
|
||||
for (const job of contract.jobs) {
|
||||
if (job.kind === "provider") {
|
||||
if (JSON.stringify(job.hostRequirements ?? []) !== sandboxRequirements) {
|
||||
issue(`provider job host requirements must equal FE-GATE-013's: ${job.id}`);
|
||||
}
|
||||
} else if (job.hostRequirements !== undefined) {
|
||||
issue(`only a provider job declares host requirements of its own: ${job.id}`);
|
||||
}
|
||||
}
|
||||
if (JSON.stringify(contract.jobs.map(({ id }) => id)) !== JSON.stringify(Object.keys(expectedJobOwnership))) {
|
||||
issue("job registry must contain the exact thirteen canonical jobs in semantic order");
|
||||
}
|
||||
|
||||
@@ -139,7 +139,7 @@ function baseOf(id: string): string {
|
||||
: id;
|
||||
}
|
||||
|
||||
function namesOf(id: string) {
|
||||
export function namesOf(id: string) {
|
||||
const base = baseOf(id);
|
||||
const pascal = base
|
||||
.split("-")
|
||||
@@ -884,6 +884,7 @@ export type ${pascal}CreateCommand = Readonly<{ name: string }>;
|
||||
`
|
||||
: "";
|
||||
return `import type {} from "../../../application/ports/in/application-api.ts";
|
||||
import { isAbortFailure } from "../../../contracts/errors.ts";
|
||||
${write ? `import type { MutationIntent } from "../../../contracts/mutation-intent.ts";\n` : ""}import type { Result } from "../../../contracts/result.ts";
|
||||
import {
|
||||
failOpenTelemetryPort,
|
||||
@@ -938,7 +939,8 @@ export function create${pascal}FeatureInput(
|
||||
// scale-architecture.md §24, §26: telemetry is best-effort and never changes the result.
|
||||
const events = failOpenTelemetryPort(telemetry);
|
||||
function reported<Value>(kind: string, result: Result<Value>): Result<Value> {
|
||||
if (!result.ok && result.error.kind !== "REQUEST_ABORTED") {
|
||||
// An aborted or fenced request did not fail (isAbortFailure).
|
||||
if (!result.ok && !isAbortFailure(result.error)) {
|
||||
void events.emit({
|
||||
kind,
|
||||
severity: "warning",
|
||||
@@ -1279,6 +1281,18 @@ describe("${names.id} application input", () => {
|
||||
await expect(input.listItems()).resolves.toEqual({ ok: false, error: failure });
|
||||
expect(emit).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("does not report a load a scope fence ended", async () => {
|
||||
const failure = createFailure("SCOPE_GENERATION_CHANGED", "${operationId}", 0);
|
||||
const emit = vi.fn<TelemetryPort["emit"]>();
|
||||
const input = create${pascal}FeatureInput(
|
||||
gatewayListing(async () => ({ ok: false, error: failure })),
|
||||
{ telemetry: { emit } },
|
||||
);
|
||||
|
||||
await expect(input.listItems()).resolves.toEqual({ ok: false, error: failure });
|
||||
expect(emit).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
`;
|
||||
}
|
||||
|
||||
@@ -267,11 +267,17 @@ function renderHostRequirements(
|
||||
job: CiWorkflowJob,
|
||||
index: ReturnType<typeof indexCiGateContract>,
|
||||
): string[] {
|
||||
return job.gateIds.flatMap((gateId) =>
|
||||
(index.gates.get(gateId)?.hostRequirements ?? []).map(
|
||||
(requirement) => ` # ${gateId} runner requirement: ${requirement}`,
|
||||
return [
|
||||
...job.gateIds.flatMap((gateId) =>
|
||||
(index.gates.get(gateId)?.hostRequirements ?? []).map(
|
||||
(requirement) => ` # ${gateId} runner requirement: ${requirement}`,
|
||||
),
|
||||
),
|
||||
);
|
||||
// 1101/13-03. A provider job runs the provider sandbox and has no gate.
|
||||
...(job.hostRequirements ?? []).map(
|
||||
(requirement) => ` # provider sandbox runner requirement: ${requirement}`,
|
||||
),
|
||||
];
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@@ -25,8 +25,8 @@ Bash 직후 ──> post-bash ──> desktop에서 pnpm·게이트를 돌
|
||||
| N2 | 같은 때, `*.md` | `scripts/check-work-docs.py`를 돌린다(작업 매뉴얼의 분량·이력 ID·뼈대·상대 링크) | 실패 줄. 고친 문서를 가리키는 줄이 있으면 그것만 |
|
||||
| N5 | Stop | 이 세션에서 desktop만 확인할 수 있는 파일(아래 밖의 모든 파일)을 고친 뒤 desktop 실행이 없으면 턴을 한 번 막고 이유를 준다 | `decision: block`, 다음 편집 전까지 한 번 |
|
||||
|
||||
- N5가 "desktop 실행"으로 치는 것: `ssh <desktop 호스트> …`로 pnpm·`ci:gate`·`verify.sh`·vitest·playwright·`node scripts/…`를 돌린 명령, 또는 `scripts/verify.sh`를 `docs`·`hooks` 밖 단계로(`--on here` 없이) 돌린 명령.
|
||||
- N5가 세지 않는 파일(노트북에서 확인되는 것): `.claude/`, `scripts/hooks/`, `scripts/tests/`, `scripts/check-work-docs.py`, `docs/ledger/`, `CLAUDE.md`, `src/**/AGENTS.md`·`CLAUDE.md`. 이것들은 `scripts/verify.sh docs`·`hooks`가 노트북에서 본다.
|
||||
- N5가 "desktop 실행"으로 치는 것: `ssh <desktop 호스트> …`로 pnpm·`ci:gate`·`verify.sh`·vitest·playwright·`node scripts/…`를 돌린 명령(로그를 읽기만 하는 `cat`·`grep`·`tail` 등은 빼고), 또는 `scripts/verify.sh`를 명령으로 `docs`·`hooks` 밖 단계로(`--on here`·`--dry-run` 없이) 돌린 명령. 앞의 `VAR=값`과 `timeout`·`nohup`·`bash` 같은 감싸는 낱말, ssh 옵션과 그 값(`-o BatchMode=yes`, `-p 22`)은 건너뛴다. `verify.sh`를 읽는 명령(`sed`, `grep`, `git log -- scripts/verify.sh`)은 세지 않는다.
|
||||
- N5가 세지 않는 파일(노트북에서 확인되는 것): `.claude/`의 설정·훅 상태, `scripts/hooks/`·`scripts/tests/`의 코드, `scripts/check-work-docs.py`, `docs/ledger/`의 장부. 이것들은 `scripts/verify.sh docs`·`hooks`가 노트북에서 본다. 그 폴더의 문서(`.md`)와 `CLAUDE.md`, `src/**/AGENTS.md`·`CLAUDE.md`는 desktop `verify:documentation`도 보므로 센다.
|
||||
- N5가 기억하는 것은 `.claude/hook-state/<session_id>.json`이다(git이 무시한다).
|
||||
- 권한 쪽 차단: `.claude/settings.json`의 `permissions.deny`가 실제 `.env`·`.env.local`·`.env.*.local`·`.env.<mode>` 읽기·쓰기를 막는다. `.env.example`은 막지 않는다.
|
||||
|
||||
|
||||
+70
-18
@@ -70,21 +70,32 @@ DOC_CHECK = ("scripts/check-work-docs.py",)
|
||||
DOC_TIMEOUT = 20
|
||||
|
||||
# --- N5: an edit that only the desktop can check, until a desktop run --------------------------------------
|
||||
# Laptop-checkable on their own: the hooks and their tests, the work-manual checker, the ledger, Claude
|
||||
# settings, CLAUDE.md and the folder rule books under src/ (scripts/check-work-docs.py checks them). Everything else is checked by gates that need pnpm.
|
||||
# Laptop-checkable on their own: the hooks and their tests, the work-manual checker, the ledger and the
|
||||
# Claude settings, documents left out. Everything else is checked by gates that need pnpm, documents
|
||||
# included: verify:documentation reads CLAUDE.md, the folder rule books under src/, .claude/**/*.md and
|
||||
# the module READMEs of scripts/hooks/ and docs/ledger/ too (1112/08-04).
|
||||
LAPTOP_ONLY = (
|
||||
re.compile(r"^\.claude/"),
|
||||
re.compile(r"^scripts/hooks/"),
|
||||
re.compile(r"^scripts/tests/"),
|
||||
re.compile(r"^\.claude/(?!.*\.md$)"),
|
||||
re.compile(r"^scripts/hooks/(?!.*\.md$)"),
|
||||
re.compile(r"^scripts/tests/(?!.*\.md$)"),
|
||||
re.compile(r"^scripts/check-work-docs\.py$"),
|
||||
re.compile(r"^docs/ledger/"),
|
||||
re.compile(r"^CLAUDE\.md$"),
|
||||
re.compile(r"^src/(?:.+/)?(?:AGENTS|CLAUDE)\.md$"),
|
||||
re.compile(r"^docs/ledger/(?!.*\.md$)"),
|
||||
)
|
||||
DESKTOP_HOST = re.compile(r"desktop")
|
||||
DESKTOP_WORK = re.compile(r"\b(?:pnpm|ci:gate|verify\.sh|vitest|playwright)\b|\bnode\s+scripts/")
|
||||
VERIFY = re.compile(r"(?:^|[\s;&|(])(?:\./)?scripts/verify\.sh\s+(\S+)(.*)")
|
||||
LAPTOP_STAGES = {"docs", "hooks"}
|
||||
# 1112/08-09. One command of a shell line: what follows ;, &&, ||, |, ( or a newline.
|
||||
COMMAND_SEPARATOR = re.compile(r"&&|\|\||;|\||\(|\)|\n")
|
||||
# Words that run the next command: `timeout 900 scripts/verify.sh …`, `bash scripts/verify.sh …`.
|
||||
WRAPPERS = {"timeout": 1, "nohup": 0, "setsid": 0, "env": 0, "time": 0, "exec": 0, "bash": 0, "sh": 0}
|
||||
# ssh options that take the next word as their value (`ssh -o BatchMode=yes desktop …`).
|
||||
SSH_VALUE_OPTIONS = {"-B", "-b", "-c", "-D", "-E", "-e", "-F", "-I", "-i", "-J", "-L", "-l", "-m", "-O",
|
||||
"-o", "-P", "-p", "-Q", "-R", "-S", "-W", "-w"}
|
||||
# A remote command made only of these reads logs; it runs nothing.
|
||||
READ_ONLY = {"cat", "grep", "tail", "head", "less", "ls", "sed", "awk", "wc", "find", "stat", "echo",
|
||||
"printf", "date", "uptime", "ps", "test", "true", "for", "do", "done", "if", "then", "fi"}
|
||||
ASSIGNMENT = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=")
|
||||
STEP_WORD = re.compile(r"^[a-z][a-z0-9-]*$")
|
||||
|
||||
|
||||
# ----------------------------------------------------------------------------------------------------
|
||||
@@ -277,20 +288,61 @@ def needs_desktop(path: str) -> bool:
|
||||
return not any(pattern.search(path) for pattern in LAPTOP_ONLY)
|
||||
|
||||
|
||||
def ran_on_desktop(command: str) -> bool:
|
||||
"""An `ssh <desktop> …` running pnpm or a gate, or scripts/verify.sh with a stage that goes there."""
|
||||
def split_words(text: str) -> list[str]:
|
||||
try:
|
||||
words = shlex.split(command)
|
||||
return shlex.split(text)
|
||||
except ValueError:
|
||||
words = command.split()
|
||||
return text.split()
|
||||
|
||||
|
||||
def command_words(segment: str) -> list[str]:
|
||||
"""The words of one command, its leading `VAR=value` and wrapper words dropped."""
|
||||
words = split_words(segment)
|
||||
while words:
|
||||
if ASSIGNMENT.match(words[0]):
|
||||
words = words[1:]
|
||||
elif words[0] in WRAPPERS:
|
||||
words = words[1 + WRAPPERS[words[0]]:]
|
||||
else:
|
||||
break
|
||||
return words
|
||||
|
||||
|
||||
def ssh_host_and_remote(words: list[str]) -> tuple[str | None, str]:
|
||||
"""The host and the remote command of the words after `ssh`, its options and their values skipped."""
|
||||
position = 0
|
||||
while position < len(words) and words[position].startswith("-"):
|
||||
position += 2 if words[position] in SSH_VALUE_OPTIONS else 1
|
||||
if position >= len(words):
|
||||
return None, ""
|
||||
return words[position], " ".join(words[position + 1:])
|
||||
|
||||
|
||||
def runs_only_reads(remote: str) -> bool:
|
||||
segments = [command_words(part) for part in COMMAND_SEPARATOR.split(remote)]
|
||||
return all(not words or words[0] in READ_ONLY for words in segments)
|
||||
|
||||
|
||||
def ran_on_desktop(command: str) -> bool:
|
||||
"""An `ssh <desktop> …` running pnpm or a gate, or scripts/verify.sh running a step that goes there.
|
||||
|
||||
1112/08-09. Reading verify.sh (`sed`, `grep`, `git log -- scripts/verify.sh`), `--dry-run` and
|
||||
an ssh that only reads logs run nothing on the desktop.
|
||||
"""
|
||||
words = split_words(command)
|
||||
for position, word in enumerate(words):
|
||||
if word.endswith("ssh"):
|
||||
hosts = [w for w in words[position + 1:position + 5] if not w.startswith("-")][:2]
|
||||
if any(DESKTOP_HOST.search(host) for host in hosts) and DESKTOP_WORK.search(command):
|
||||
host, remote = ssh_host_and_remote(words[position + 1:])
|
||||
if (host is not None and DESKTOP_HOST.search(host) and DESKTOP_WORK.search(remote)
|
||||
and not runs_only_reads(remote)):
|
||||
return True
|
||||
for match in VERIFY.finditer(command):
|
||||
stage, rest = match.group(1), match.group(2)
|
||||
if stage not in LAPTOP_STAGES and not re.search(r"--on\s+here\b", rest):
|
||||
for segment in COMMAND_SEPARATOR.split(command):
|
||||
words = command_words(segment)
|
||||
if len(words) < 2 or not re.search(r"(?:^|/)scripts/verify\.sh$", words[0]):
|
||||
continue
|
||||
step, flags = words[1], words[2:]
|
||||
if (STEP_WORD.match(step) and step not in LAPTOP_STAGES and "--dry-run" not in flags
|
||||
and not re.search(r"--on\s+here\b", " ".join(flags))):
|
||||
return True
|
||||
return False
|
||||
|
||||
|
||||
@@ -0,0 +1,25 @@
|
||||
/**
|
||||
* 1112/08-13. What a failed `ci:gate` prints to stderr: the gate, the command
|
||||
* that failed (or that none did), the log with the whole output, and the end
|
||||
* of that output, where the cause usually is.
|
||||
*/
|
||||
export function formatGateFailure(input: Readonly<{
|
||||
gateId: string;
|
||||
gateName: string;
|
||||
logPath: string;
|
||||
failedCommand?: string | undefined;
|
||||
output: readonly string[];
|
||||
tailLines?: number;
|
||||
}>): string {
|
||||
const tail = input.output
|
||||
.flatMap((chunk) => chunk.split(/\r?\n/u))
|
||||
.filter((line) => line.trim() !== "")
|
||||
.slice(-(input.tailLines ?? 20));
|
||||
return [
|
||||
`${input.gateId} ${input.gateName}: FAIL`,
|
||||
` failed command: ${input.failedCommand ?? "none (a check outside the commands)"}`,
|
||||
` log: ${input.logPath}`,
|
||||
" last lines of the log:",
|
||||
...tail.map((line) => ` ${line}`),
|
||||
].join("\n");
|
||||
}
|
||||
@@ -0,0 +1,70 @@
|
||||
/**
|
||||
* 0929/13-04. What the declared Content-Security-Policy
|
||||
* (config/hosting/security-headers.json) may not allow.
|
||||
* scripts/verify-hosting-headers.ts compares a host's answer with it; this
|
||||
* reads what it allows. check:browser-security (FE-GATE-013) runs it, and
|
||||
* check:security:fixtures (FE-GATE-029) holds it to a rejected fixture.
|
||||
*/
|
||||
const UNSAFE_SOURCES = new Set(["'unsafe-inline'", "'unsafe-eval'", "*"]);
|
||||
/** Directives whose sources decide what script or plugin code may run or style may apply. */
|
||||
const CODE_DIRECTIVES = new Set([
|
||||
"default-src",
|
||||
"script-src",
|
||||
"script-src-elem",
|
||||
"script-src-attr",
|
||||
"style-src",
|
||||
"style-src-elem",
|
||||
"style-src-attr",
|
||||
"object-src",
|
||||
]);
|
||||
/** A scheme-only source (`https:`) lets any host on it run script. */
|
||||
const SCHEME_ONLY = /^[a-z][a-z0-9+.-]*:$/u;
|
||||
const SCRIPT_DIRECTIVES = new Set(["default-src", "script-src", "script-src-elem", "object-src"]);
|
||||
|
||||
/**
|
||||
* The directives as a browser reads them (CSP3): names and keywords in any
|
||||
* case, and the first of a repeated directive, the later ones ignored.
|
||||
*/
|
||||
function directivesOf(policy: string): Map<string, readonly string[]> {
|
||||
const directives = new Map<string, readonly string[]>();
|
||||
for (const part of policy.split(";")) {
|
||||
const [name, ...sources] = part.trim().split(/\s+/u);
|
||||
const key = name?.toLowerCase();
|
||||
if (key && !directives.has(key)) {
|
||||
directives.set(key, sources.map((source) => source.toLowerCase()));
|
||||
}
|
||||
}
|
||||
return directives;
|
||||
}
|
||||
|
||||
export function cspPolicyProblems(policy: string): string[] {
|
||||
const directives = directivesOf(policy);
|
||||
const problems: string[] = [];
|
||||
if (!directives.has("script-src") && !directives.has("default-src")) {
|
||||
problems.push("no script-src and no default-src");
|
||||
}
|
||||
for (const [name, sources] of directives) {
|
||||
if (!CODE_DIRECTIVES.has(name)) continue;
|
||||
for (const source of sources) {
|
||||
if (UNSAFE_SOURCES.has(source)) problems.push(`${name} allows ${source}`);
|
||||
else if (SCRIPT_DIRECTIVES.has(name) && SCHEME_ONLY.test(source)) {
|
||||
problems.push(`${name} allows the whole scheme ${source}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
return problems;
|
||||
}
|
||||
|
||||
/**
|
||||
* The problems of the policy a security-headers document (the shape of
|
||||
* config/hosting/security-headers.json) declares, its header name in any case.
|
||||
*/
|
||||
export function declaredCspProblems(securityHeadersJson: string): string[] {
|
||||
const document = JSON.parse(securityHeadersJson) as { headers?: Record<string, unknown> };
|
||||
const policy = Object.entries(document.headers ?? {}).find(
|
||||
([name]) => name.toLowerCase() === "content-security-policy",
|
||||
)?.[1];
|
||||
return typeof policy === "string"
|
||||
? cspPolicyProblems(policy)
|
||||
: ["no Content-Security-Policy header"];
|
||||
}
|
||||
+129
-12
@@ -9,8 +9,16 @@ import path from "node:path";
|
||||
* - `src/`: any file whose path or text still names the feature ID or its
|
||||
* folder. Platform source never names a product feature, so a name left
|
||||
* there is a reference the type checker cannot see (a catalog key, a
|
||||
* runtime override, a link).
|
||||
* - `tests/`: a file named after the feature, or one that imports from the
|
||||
* runtime override, a link). The name counts as a whole name only: in the
|
||||
* text, case-sensitive with no identifier character (`[A-Za-z0-9_-]`) on
|
||||
* either side; in the path, a segment equal to it or whose part before the
|
||||
* first `.` is. A substring search counted ten template files for
|
||||
* `product-feature` (`product-features.ts`, `product-features-port.ts` and
|
||||
* their importers). `src/.generated/` is derived from the feature list and
|
||||
* left out. A one-word ID that is an ordinary word in the template
|
||||
* (`search`) can still be found in its text.
|
||||
* - `tests/`: a file named after the feature (the same path rule; the
|
||||
* template's `product-feature-switch.test.tsx` is not), or one that imports from the
|
||||
* feature's `src/features/<dir>/` or `tests/features/<dir>/`. A vitest
|
||||
* test's text is not searched for the bare name: the template's own tests
|
||||
* use example IDs as data (`tests/unit/create-feature.test.ts` writes
|
||||
@@ -25,14 +33,24 @@ import path from "node:path";
|
||||
* searched for the ID or folder name as written, case-sensitive, with no
|
||||
* identifier character (`[A-Za-z0-9_-]`) on either side. A longer name
|
||||
* that contains it (`generate-product-feature-index.ts` for
|
||||
* `product-feature`, `KO_MESSAGES` for `messages`) does not count. A spec
|
||||
* that names only the feature's routes or URLs is not found; 03's hand list
|
||||
* removes the feature's specs.
|
||||
* `product-feature`, `KO_MESSAGES` for `messages`) does not count.
|
||||
* Diff review DR-02: only a name with a hyphen is searched. A one-word ID
|
||||
* or folder (`status`, `reports`, `messages`) is an ordinary word in the
|
||||
* template's own specs (`status: 200`, `getByRole("status")`, "reports" in
|
||||
* a test title), and no text rule tells that from a reference, so a spec
|
||||
* that names only a one-word ID is not found either.
|
||||
* a test title), and no text rule tells that from a reference.
|
||||
* - 0925 FOLLOW-UP 09-07. A spec that opens the feature by its URL alone
|
||||
* (`page.goto("/invoices")`) failed only in FE-GATE-008, after the drill
|
||||
* passed. `routes.paths` are the removed feature's route paths: a spec, or
|
||||
* another file in a Playwright `testDir` that is not a vitest test (a page
|
||||
* object), with a string that opens one is residue. A string opens a route
|
||||
* when it starts with the route's fixed prefix (`/invoices` of
|
||||
* `/invoices/:id` or `/invoices/edit?`) followed by the string's end, `/`,
|
||||
* `?`, `#` or `${`, and no route left behind (`routes.remainingPaths`) has
|
||||
* a longer prefix that fits it. A prefix that is `/` is not searched.
|
||||
* `routes.ids`, the feature's route IDs, are searched in `src` text by the
|
||||
* whole-name rule. What is still not found: a spec that names only a
|
||||
* one-word ID, or builds the URL from parts. 03's hand list removes the
|
||||
* feature's specs.
|
||||
*
|
||||
* The drill applies the same rule to a sample a project lists in
|
||||
* scripts/lib/removable-template-features.ts.
|
||||
@@ -41,6 +59,18 @@ function escapeRegExp(value: string): string {
|
||||
return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
|
||||
}
|
||||
|
||||
/**
|
||||
* The feature ID or folder as a whole name: case-sensitive, with no
|
||||
* identifier character (`[A-Za-z0-9_-]`) on either side. The drill searches
|
||||
* `src` text and the built `dist` with it; the template's own bundle holds
|
||||
* `data-product-feature` and `product-features`, which a substring search
|
||||
* counted for a feature named `product-feature`.
|
||||
*/
|
||||
export function featureNamePattern(featureId: string, directory: string): RegExp {
|
||||
const names = [...new Set([featureId, directory])].map(escapeRegExp).join("|");
|
||||
return new RegExp(`(?<![A-Za-z0-9_-])(?:${names})(?![A-Za-z0-9_-])`, "u");
|
||||
}
|
||||
|
||||
async function filesUnder(directory: string): Promise<string[]> {
|
||||
const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
|
||||
const nested = await Promise.all(
|
||||
@@ -52,13 +82,73 @@ async function filesUnder(directory: string): Promise<string[]> {
|
||||
return nested.flat();
|
||||
}
|
||||
|
||||
/**
|
||||
* The part of a route path before its first parameter, wildcard or optional
|
||||
* segment (`/invoices` of `/invoices/:id` or `/invoices/edit?`), or null when
|
||||
* that is `/`.
|
||||
*/
|
||||
function staticRoutePrefix(routePath: string): string | null {
|
||||
const segments: string[] = [];
|
||||
for (const segment of routePath.split("/").filter(Boolean)) {
|
||||
if (segment.startsWith(":") || segment.includes("*") || segment.endsWith("?")) break;
|
||||
segments.push(segment);
|
||||
}
|
||||
return segments.length === 0 ? null : `/${segments.join("/")}`;
|
||||
}
|
||||
|
||||
const prefixesOf = (routePaths: readonly string[]) =>
|
||||
new Set(routePaths.map(staticRoutePrefix).filter((prefix): prefix is string => prefix !== null));
|
||||
|
||||
/** `/invoices`, `/invoices/7`, `/invoices?tab=1`, `/invoices#x`, `/invoices${query}` open `/invoices`. */
|
||||
function opens(value: string, prefix: string): boolean {
|
||||
if (!value.startsWith(prefix)) return false;
|
||||
const rest = value.slice(prefix.length);
|
||||
return rest === "" || /^[/?#]/u.test(rest) || rest.startsWith("${");
|
||||
}
|
||||
|
||||
/** The Playwright `testDir`s the repository's `playwright*.config.ts` files name. */
|
||||
async function browserTestDirectories(root: string): Promise<string[]> {
|
||||
const configs = (await readdir(root).catch(() => [])).filter((name) =>
|
||||
/^playwright(?:\.[\w-]+)?\.config\.[cm]?[jt]s$/u.test(name),
|
||||
);
|
||||
const directories = await Promise.all(
|
||||
configs.map(async (config) =>
|
||||
/testDir:\s*["']\.?\/?([^"']+)["']/u.exec(await readFile(path.join(root, config), "utf8"))?.[1]
|
||||
?.replace(/\/$/u, ""),
|
||||
),
|
||||
);
|
||||
return directories.filter((directory): directory is string => directory !== undefined);
|
||||
}
|
||||
|
||||
export type FeatureRoutes = Readonly<{
|
||||
/** The removed feature's route paths. */
|
||||
paths?: readonly string[];
|
||||
/** Every route path left after the removal, platform routes included. */
|
||||
remainingPaths?: readonly string[];
|
||||
/** The removed feature's route IDs, platform IDs it took over left out. */
|
||||
ids?: readonly string[];
|
||||
}>;
|
||||
|
||||
export async function productFeatureResidue(
|
||||
root: string,
|
||||
featureId: string,
|
||||
directory: string,
|
||||
routes: FeatureRoutes = {},
|
||||
): Promise<string[]> {
|
||||
const names = [...new Set([featureId, directory])].map(escapeRegExp).join("|");
|
||||
const named = new RegExp(names, "iu");
|
||||
const nameSet = new Set([featureId, directory]);
|
||||
const names = [...nameSet].map(escapeRegExp).join("|");
|
||||
const wholeAnyName = featureNamePattern(featureId, directory);
|
||||
// A route ID left in platform source (a catalog key, `route.INVOICES_LIST`)
|
||||
// is found by its whole name too.
|
||||
const routeIds = [...new Set(routes.ids ?? [])].map(escapeRegExp);
|
||||
const wholeRouteId =
|
||||
routeIds.length === 0
|
||||
? null
|
||||
: new RegExp(`(?<![A-Za-z0-9_-])(?:${routeIds.join("|")})(?![A-Za-z0-9_-])`, "u");
|
||||
const pathNames = (relativePath: string) =>
|
||||
relativePath
|
||||
.split("/")
|
||||
.some((segment) => nameSet.has(segment) || nameSet.has(segment.split(".")[0] ?? ""));
|
||||
const imported = new RegExp(
|
||||
String.raw`(?:\bfrom\s*|\bimport\s*\(\s*|\bimport\s+|\bmock\s*\(\s*)["'][^"'\n]*/features/(?:${names})/`,
|
||||
"u",
|
||||
@@ -70,20 +160,47 @@ export async function productFeatureResidue(
|
||||
specNames.length === 0
|
||||
? null
|
||||
: new RegExp(`(?<![A-Za-z0-9_-])(?:${specNames.join("|")})(?![A-Za-z0-9_-])`, "u");
|
||||
// A URL opens the route whose fixed prefix is the longest that fits it, so
|
||||
// a sibling feature's `/invoices/lines` in the same context is not the
|
||||
// removed `/invoices`. When a route left behind has the same prefix
|
||||
// (`/invoices` beside a removed `/invoices/:id`), the URL is not counted.
|
||||
const removed = prefixesOf(routes.paths ?? []);
|
||||
const remaining = prefixesOf(routes.remainingPaths ?? []);
|
||||
const candidates = [...new Set([...removed, ...remaining])].sort((a, b) => b.length - a.length);
|
||||
const opensRemovedRoute = (text: string) => {
|
||||
if (removed.size === 0) return false;
|
||||
for (const match of text.matchAll(/["'`](\/[^"'`\s]*)/gu)) {
|
||||
const best = candidates.find((prefix) => opens(match[1]!, prefix));
|
||||
if (best !== undefined && removed.has(best) && !remaining.has(best)) return true;
|
||||
}
|
||||
return false;
|
||||
};
|
||||
const browserDirectories = await browserTestDirectories(root);
|
||||
const playwrightSpec = /\.spec\.[cm]?[jt]sx?$/u;
|
||||
// A page object or helper beside the specs (`tests/e2e/support/*.ts`) runs
|
||||
// only in a browser too; a vitest test (`*.test.*`) does not.
|
||||
const browserFile = (name: string) =>
|
||||
playwrightSpec.test(name) ||
|
||||
(!/\.test\.[cm]?[jt]sx?$/u.test(name) &&
|
||||
browserDirectories.some((directory) => name.startsWith(`${directory}/`)));
|
||||
const residue: string[] = [];
|
||||
const relative = (file: string) => path.relative(root, file).split(path.sep).join("/");
|
||||
for (const file of await filesUnder(path.join(root, "src"))) {
|
||||
const name = relative(file);
|
||||
if (named.test(`${name}\n${await readFile(file, "utf8")}`)) residue.push(name);
|
||||
if (name.startsWith("src/.generated/")) continue;
|
||||
const text = await readFile(file, "utf8");
|
||||
if (pathNames(name) || wholeAnyName.test(text) || (wholeRouteId !== null && wholeRouteId.test(text))) {
|
||||
residue.push(name);
|
||||
}
|
||||
}
|
||||
for (const file of await filesUnder(path.join(root, "tests"))) {
|
||||
const name = relative(file);
|
||||
const text = await readFile(file, "utf8");
|
||||
if (
|
||||
named.test(name) ||
|
||||
pathNames(name) ||
|
||||
imported.test(text) ||
|
||||
(wholeName !== null && playwrightSpec.test(name) && wholeName.test(text))
|
||||
(playwrightSpec.test(name) && wholeName !== null && wholeName.test(text)) ||
|
||||
(browserFile(name) && opensRemovedRoute(text))
|
||||
) {
|
||||
residue.push(name);
|
||||
}
|
||||
|
||||
@@ -5,9 +5,11 @@ import { tmpdir } from "node:os";
|
||||
import path from "node:path";
|
||||
import { pathToFileURL } from "node:url";
|
||||
|
||||
import { namesOf } from "../create-feature.ts";
|
||||
import { localBuildEnvironment } from "./build-environment.ts";
|
||||
import { linkFixtureNodeModules } from "./fixture-node-modules.ts";
|
||||
import { REMOVAL_FIXTURE_COPY_TARGETS } from "./removal-fixture.ts";
|
||||
import { TEMPLATE_PROBE_PREFIX } from "./template-probe-features.ts";
|
||||
|
||||
/**
|
||||
* 2026-11-07. The template ships no feature. What needs one in a real build
|
||||
@@ -19,8 +21,19 @@ import { REMOVAL_FIXTURE_COPY_TARGETS } from "./removal-fixture.ts";
|
||||
* (scripts/scale/browser-soak.ts, `buildWithGeneratedFeature`). A change of
|
||||
* the generator's output fails there. The `--keyed` write slice is the widest
|
||||
* one the command makes.
|
||||
*
|
||||
* 1112/08-02. The id begins with the reserved probe prefix: the copy holds
|
||||
* the product's own features, and a product that had built `order-feature`
|
||||
* made create:feature refuse this one.
|
||||
*/
|
||||
export const GENERATED_FEATURE_ID = "order-feature";
|
||||
export const GENERATED_FEATURE_ID = `${TEMPLATE_PROBE_PREFIX}order-feature`;
|
||||
|
||||
const NAMES = namesOf(GENERATED_FEATURE_ID);
|
||||
|
||||
/** The key of one of the feature's words (`<camel>.list.title`). */
|
||||
export function generatedMessageKey(suffix: string): string {
|
||||
return `${NAMES.camel}.${suffix}`;
|
||||
}
|
||||
|
||||
export type GeneratedRoute = Readonly<{
|
||||
routeId: string;
|
||||
@@ -48,7 +61,7 @@ function node(root: string, args: readonly string[]): string {
|
||||
return result.stdout;
|
||||
}
|
||||
|
||||
/** The edit of a fixture build: `corepack pnpm create:feature order-feature --with-create --keyed`. */
|
||||
/** The edit of a fixture build: `corepack pnpm create:feature <GENERATED_FEATURE_ID> --with-create --keyed`. */
|
||||
export async function addGeneratedFeature(root: string): Promise<void> {
|
||||
node(root, ["scripts/generate-product-feature-index.ts"]);
|
||||
node(root, ["scripts/create-feature.ts", GENERATED_FEATURE_ID, "--with-create", "--keyed"]);
|
||||
@@ -62,23 +75,24 @@ export async function addGeneratedFeature(root: string): Promise<void> {
|
||||
export function generatedFeature(root: string): GeneratedFeature {
|
||||
const feature = path.join(root, "src/features", GENERATED_FEATURE_ID);
|
||||
const module = (file: string) => JSON.stringify(pathToFileURL(path.join(feature, file)).href);
|
||||
const { base, upper } = NAMES;
|
||||
const source = `
|
||||
const { ORDER_FEATURE_CONTRACT } = await import(${module("contracts/order-feature-contract.ts")});
|
||||
const { ORDER_MESSAGE_CATALOGS } = await import(${module("contracts/order-message-catalog.ts")});
|
||||
const { ORDER_LIST_ITEMS_CONTRACT } = await import(${module("contracts/order-contract-contribution.ts")});
|
||||
const { ${upper}_FEATURE_CONTRACT: CONTRACT } = await import(${module(`contracts/${GENERATED_FEATURE_ID}-contract.ts`)});
|
||||
const { ${upper}_MESSAGE_CATALOGS: CATALOGS } = await import(${module(`contracts/${base}-message-catalog.ts`)});
|
||||
const { ${upper}_LIST_ITEMS_CONTRACT: LIST_ITEMS } = await import(${module(`contracts/${base}-contract-contribution.ts`)});
|
||||
const { API_BASE_URL } = JSON.parse(await (await import("node:fs/promises")).readFile("config/runtime/local.json", "utf8"));
|
||||
const route = (id) => ({
|
||||
routeId: id,
|
||||
path: ORDER_FEATURE_CONTRACT.routes[id].path,
|
||||
chunkId: ORDER_FEATURE_CONTRACT.routes[id].chunkId,
|
||||
moduleId: ORDER_FEATURE_CONTRACT.routeRuntimeContracts[id].moduleId,
|
||||
path: CONTRACT.routes[id].path,
|
||||
chunkId: CONTRACT.routes[id].chunkId,
|
||||
moduleId: CONTRACT.routeRuntimeContracts[id].moduleId,
|
||||
});
|
||||
process.stdout.write(JSON.stringify({
|
||||
list: route("ORDER_LIST"),
|
||||
detail: route("ORDER_DETAIL"),
|
||||
create: route("ORDER_CREATE"),
|
||||
messages: ORDER_MESSAGE_CATALOGS,
|
||||
api: new URL(ORDER_LIST_ITEMS_CONTRACT.contract.pathTemplate.slice(1), API_BASE_URL).href,
|
||||
list: route("${upper}_LIST"),
|
||||
detail: route("${upper}_DETAIL"),
|
||||
create: route("${upper}_CREATE"),
|
||||
messages: CATALOGS,
|
||||
api: new URL(LIST_ITEMS.contract.pathTemplate.slice(1), API_BASE_URL).href,
|
||||
}));
|
||||
`;
|
||||
return JSON.parse(node(root, ["--input-type=module", "-e", source])) as GeneratedFeature;
|
||||
|
||||
@@ -3,6 +3,8 @@ import { mkdtemp, readFile, rm } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import path from "node:path";
|
||||
|
||||
import { declaredCspProblems } from "./csp-policy.ts";
|
||||
|
||||
type ScanResult = Readonly<{
|
||||
error?: Error;
|
||||
status: number | null;
|
||||
@@ -168,3 +170,25 @@ export async function checkNonmatchingSecurityIncludeFixture(
|
||||
await cleanup(directory);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 0929/13-04. The policy check check:browser-security runs rejects its
|
||||
* fixture (a keyword in another case, in the first of two script-src) and
|
||||
* accepts the declared policy.
|
||||
*/
|
||||
export async function checkDeclaredCspFixtures(): Promise<void> {
|
||||
const fixture = "tests/fixtures/security/csp/rejected-security-headers.json";
|
||||
const rejected = declaredCspProblems(await readFile(fixture, "utf8"));
|
||||
const expected = ["script-src allows 'unsafe-inline'"];
|
||||
if (JSON.stringify(rejected) !== JSON.stringify(expected)) {
|
||||
throw new Error(
|
||||
`${fixture}: expected ${expected.join(", ")}; received ${rejected.join(", ") || "no problem"}`,
|
||||
);
|
||||
}
|
||||
const declared = declaredCspProblems(
|
||||
await readFile("config/hosting/security-headers.json", "utf8"),
|
||||
);
|
||||
if (declared.length > 0) {
|
||||
throw new Error(`config/hosting/security-headers.json: ${declared.join("; ")}`);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,49 @@
|
||||
import { namesOf } from "../create-feature.ts";
|
||||
|
||||
/**
|
||||
* 1112/08-02. Feature ids the template's own tests and drills create in a
|
||||
* copy of the repository. The copy holds the product's features, and
|
||||
* create:feature refuses an id a feature there already has, or one with the
|
||||
* same prefix. A template test that used the manual's example
|
||||
* (`invoice-feature`) or a plain business word (`order-feature`) therefore
|
||||
* failed FE-GATE-005 and FE-GATE-008 in every product that had built a
|
||||
* feature by that name. Each id here begins with the prefix the template
|
||||
* reserves for its probes; docs/manual/reference/create-feature.md tells a
|
||||
* product not to use it.
|
||||
*/
|
||||
export const TEMPLATE_PROBE_PREFIX = "typecheck-probe-";
|
||||
|
||||
/** The feature the manual's code blocks are written for (docs/manual/01-add-a-feature.md). */
|
||||
export const MANUAL_EXAMPLE_FEATURE_ID = "invoice-feature";
|
||||
/** What tests/unit/manual-code-blocks.test.ts creates and renames the blocks to. */
|
||||
export const MANUAL_PROBE_FEATURE_ID = `${TEMPLATE_PROBE_PREFIX}${MANUAL_EXAMPLE_FEATURE_ID}`;
|
||||
/** The sample tests/unit/template-feature-removal-documents.test.ts lists and deletes. */
|
||||
export const LISTED_SAMPLE_PROBE_FEATURE_ID = `${TEMPLATE_PROBE_PREFIX}listed-sample-feature`;
|
||||
/** What FE-GATE-020's scaffold drill (scripts/test-feature-scaffold.ts, test:sample-removal) creates. */
|
||||
export const SCAFFOLD_PROBE_FEATURE_ID = `${TEMPLATE_PROBE_PREFIX}scaffold-feature`;
|
||||
/** The scaffold drill's `--with-create --keyed` feature. */
|
||||
export const SCAFFOLD_WRITE_PROBE_FEATURE_ID = `${TEMPLATE_PROBE_PREFIX}scaffold-write-feature`;
|
||||
|
||||
function escape(text: string): string {
|
||||
return text.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
|
||||
}
|
||||
|
||||
/**
|
||||
* `text` written for feature `fromId`, with every spelling create:feature
|
||||
* derives from an id (`INVOICE_`, `Invoice`, `invoice-`, `invoice`) moved to
|
||||
* the spelling it derives from `toId`. Prose that uses the word moves too;
|
||||
* what matters is that the names a block defines and the names it imports
|
||||
* from the generated feature move together.
|
||||
*/
|
||||
export function renameFeatureText(text: string, fromId: string, toId: string): string {
|
||||
const from = namesOf(fromId);
|
||||
const to = namesOf(toId);
|
||||
const spellings = new Map<string, string>([
|
||||
[from.upper, to.upper],
|
||||
[from.pascal, to.pascal],
|
||||
[`${from.base}-`, `${to.base}-`],
|
||||
[from.camel, to.camel],
|
||||
]);
|
||||
const pattern = new RegExp([...spellings.keys()].map(escape).join("|"), "gu");
|
||||
return text.replace(pattern, (match) => spellings.get(match) ?? match);
|
||||
}
|
||||
@@ -16,6 +16,15 @@ import { reachablePackageScripts } from "./package-script-graph.ts";
|
||||
export const UNGATED_TESTS_PATH = "config/ci/ungated-tests.json";
|
||||
|
||||
const TEST_FILE = /\.(?:test|spec)\.tsx?$/u;
|
||||
// vitest.config.ts includes only the `*.test.ts` and `*.test.tsx` files below tests.
|
||||
const VITEST_TEST_FILE = /\.test\.tsx?$/u;
|
||||
|
||||
/**
|
||||
* 0929/12-06. A gated path and the runner that reaches it. A Vitest path
|
||||
* runs its `*.test.*` files only; a Playwright `testDir` runs what the
|
||||
* Playwright default `testMatch` takes, `*.spec.*` and `*.test.*`.
|
||||
*/
|
||||
export type GatedTestTarget = Readonly<{ path: string; runner: "vitest" | "playwright" }>;
|
||||
|
||||
const ungatedTestsSchema = z
|
||||
.object({
|
||||
@@ -54,14 +63,26 @@ export function gatedTestPaths(
|
||||
entryScripts: readonly string[],
|
||||
readConfig: (file: string) => string,
|
||||
): string[] {
|
||||
const paths = new Set<string>();
|
||||
return [...new Set(gatedTestTargets(scripts, entryScripts, readConfig).map(({ path: target }) => target))].sort();
|
||||
}
|
||||
|
||||
export function gatedTestTargets(
|
||||
scripts: Readonly<Record<string, string>>,
|
||||
entryScripts: readonly string[],
|
||||
readConfig: (file: string) => string,
|
||||
): GatedTestTarget[] {
|
||||
const targets = new Map<string, GatedTestTarget>();
|
||||
const add = (target: string, runner: GatedTestTarget["runner"]) => {
|
||||
const normalized = target.replace(/\/$/u, "");
|
||||
targets.set(`${runner} ${normalized}`, { path: normalized, runner });
|
||||
};
|
||||
const addVitestPaths = (tokens: readonly string[]) => {
|
||||
const vitestRun = tokens.findIndex(
|
||||
(token, index) => token === "run" && /(?:run-vitest\.ts|vitest)$/u.test(tokens[index - 1] ?? ""),
|
||||
);
|
||||
if (vitestRun < 0) return;
|
||||
for (const token of tokens.slice(vitestRun + 1)) {
|
||||
if (!token.startsWith("-")) paths.add(token.replace(/\/$/u, ""));
|
||||
if (!token.startsWith("-")) add(token, "vitest");
|
||||
}
|
||||
};
|
||||
for (const script of reachablePackageScripts(scripts, entryScripts)) {
|
||||
@@ -79,20 +100,30 @@ export function gatedTestPaths(
|
||||
const configFlag = tokens.indexOf("--config");
|
||||
const config = configFlag >= 0 ? tokens[configFlag + 1]! : "playwright.config.ts";
|
||||
const testDir = /testDir:\s*["']\.?\/?([^"']+)["']/u.exec(readConfig(config))?.[1];
|
||||
if (testDir) paths.add(testDir.replace(/\/$/u, ""));
|
||||
if (testDir) add(testDir, "playwright");
|
||||
}
|
||||
}
|
||||
}
|
||||
return [...paths].sort();
|
||||
return [...targets.values()].sort(
|
||||
(left, right) => left.path.localeCompare(right.path) || left.runner.localeCompare(right.runner),
|
||||
);
|
||||
}
|
||||
|
||||
export function ungatedTestFailures(input: Readonly<{
|
||||
testFiles: readonly string[];
|
||||
gatedPaths: readonly string[];
|
||||
/** A bare string is a Vitest path. */
|
||||
gatedPaths: readonly (string | GatedTestTarget)[];
|
||||
exclusions: readonly UngatedTestExclusion[];
|
||||
}>): string[] {
|
||||
const targets = input.gatedPaths.map((target): GatedTestTarget =>
|
||||
typeof target === "string" ? { path: target, runner: "vitest" } : target,
|
||||
);
|
||||
const gated = (file: string) =>
|
||||
input.gatedPaths.some((gatedPath) => file === gatedPath || file.startsWith(`${gatedPath}/`));
|
||||
targets.some(
|
||||
({ path: gatedPath, runner }) =>
|
||||
(file === gatedPath || file.startsWith(`${gatedPath}/`)) &&
|
||||
(runner === "playwright" || VITEST_TEST_FILE.test(file)),
|
||||
);
|
||||
const excluded = new Set(input.exclusions.map(({ path: file }) => file));
|
||||
const failures = input.testFiles
|
||||
.filter((file) => !gated(file) && !excluded.has(file))
|
||||
|
||||
@@ -30,6 +30,7 @@ import {
|
||||
type ProviderGuardianLease,
|
||||
} from "./lib/provider-guardian-client.ts";
|
||||
import { createProviderOutputLimiter } from "./lib/provider-output-limiter.ts";
|
||||
import { findProviderSandboxNamespaceFailure } from "./check-system-test-prerequisites.ts";
|
||||
import { PROVIDER_SANDBOX_NAMESPACE_ARGUMENTS } from "./lib/provider-sandbox-namespaces.ts";
|
||||
import {
|
||||
providerProcessTraceEnvironment,
|
||||
@@ -125,6 +126,13 @@ await access("/usr/bin/systemd-run", constants.X_OK).catch(() => {
|
||||
await access("/usr/bin/systemctl", constants.X_OK).catch(() => {
|
||||
throw new Error("provider cgroup unavailable: /usr/bin/systemctl is required");
|
||||
});
|
||||
// 1101/13-03. A runner that refuses the sandbox's unprivileged user and
|
||||
// network namespaces fails here, by name and with its host settings, instead
|
||||
// of later with bwrap's raw error.
|
||||
const namespaceFailure = await findProviderSandboxNamespaceFailure();
|
||||
if (namespaceFailure !== undefined) {
|
||||
throw new Error(`provider sandbox unavailable: ${namespaceFailure}`);
|
||||
}
|
||||
await assertProviderCgroupManagerAvailable();
|
||||
const trust = await readProviderTrust(workspaceRoot, publicKeyPath, keyId);
|
||||
if (!trust) throw new TypeError("provider supervisor trust key is invalid");
|
||||
|
||||
+12
-1
@@ -11,6 +11,7 @@ import {
|
||||
import { classifyGateStepResult } from "./lib/ci-step-result.ts";
|
||||
import { withCiGatePreflight } from "./contracts/ci-gates.ts";
|
||||
import { validateCiArtifact } from "./lib/ci-artifact-validator.ts";
|
||||
import { formatGateFailure } from "./lib/ci-gate-failure.ts";
|
||||
import { writeCiGateLogAtomic } from "./lib/ci-gate-log.ts";
|
||||
|
||||
const requestedGateId = process.argv
|
||||
@@ -111,6 +112,7 @@ for (const variable of gate.requiresEnvironment ?? []) {
|
||||
}
|
||||
}
|
||||
|
||||
let failedCommand: string | undefined;
|
||||
if (passed) {
|
||||
for (const commandId of gate.commandIds) {
|
||||
const step = contractIndex.commands.get(commandId);
|
||||
@@ -174,6 +176,7 @@ if (passed) {
|
||||
});
|
||||
if (!appendOutput(`classification: ${classification.kind}`)) passed = false;
|
||||
if (!classification.expectationMet) {
|
||||
failedCommand = commandLine;
|
||||
appendOutput(
|
||||
`expectation failed: expected ${step.expect}, exit=${result.status}, signal=${result.signal ?? "none"}`,
|
||||
...(step.expect === "fail"
|
||||
@@ -241,7 +244,15 @@ if (passed) {
|
||||
}
|
||||
|
||||
if (!passed) {
|
||||
process.stderr.write(`${gateId} ${gate.name}: FAIL\n`);
|
||||
process.stderr.write(
|
||||
`${formatGateFailure({
|
||||
gateId,
|
||||
gateName: gate.name,
|
||||
logPath: logArtifact.path,
|
||||
failedCommand,
|
||||
output,
|
||||
})}\n`,
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
process.stdout.write(
|
||||
|
||||
@@ -4,6 +4,10 @@ import { mkdir, rm, writeFile } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
import { loadCiGateContract } from "./contracts/ci-gates.ts";
|
||||
import {
|
||||
SCAFFOLD_PROBE_FEATURE_ID,
|
||||
SCAFFOLD_WRITE_PROBE_FEATURE_ID,
|
||||
} from "./lib/template-probe-features.ts";
|
||||
import {
|
||||
runScaffoldDrillCommand,
|
||||
scaffoldDrillCommands,
|
||||
@@ -37,9 +41,10 @@ import {
|
||||
* test:sample-removal repeats the generation after deleting the sample
|
||||
* (decision 4), which proves the command needs nothing from it.
|
||||
*/
|
||||
const FEATURE_ID = "scaffold-feature";
|
||||
/** 1112/08-02. Reserved probe ids: the copy holds the product's own features. */
|
||||
const FEATURE_ID = SCAFFOLD_PROBE_FEATURE_ID;
|
||||
/** 1103/09-06. The `--with-create --keyed` slice, in its own context. */
|
||||
const WRITE_FEATURE_ID = "scaffold-write-feature";
|
||||
const WRITE_FEATURE_ID = SCAFFOLD_WRITE_PROBE_FEATURE_ID;
|
||||
const REPORT = "artifacts/tests/feature-scaffold.xml";
|
||||
|
||||
const pnpmCli = requireRemovalFixtureEnvironment("npm_execpath");
|
||||
|
||||
@@ -10,10 +10,11 @@ import { spawnSync } from "node:child_process";
|
||||
import path from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
|
||||
import { ROUTE_FEATURE_OWNER } from "../src/features/installed-feature-contracts.ts";
|
||||
import { PLATFORM_ROUTE_REGISTRY } from "../src/contracts/routes.ts";
|
||||
import { ROUTE_FEATURE_OWNER, routePath } from "../src/features/installed-feature-contracts.ts";
|
||||
import { loadCiGateContract } from "./contracts/ci-gates.ts";
|
||||
import { createFileSystemDeclarationSource } from "./generate-product-feature-index.ts";
|
||||
import { productFeatureResidue } from "./lib/feature-residue.ts";
|
||||
import { featureNamePattern, type FeatureRoutes, productFeatureResidue } from "./lib/feature-residue.ts";
|
||||
import { isProductionModulePath } from "./lib/risk-coverage.ts";
|
||||
import {
|
||||
createRemovalFixtureRoot,
|
||||
@@ -33,6 +34,7 @@ import {
|
||||
} from "./lib/removal-fixture.ts";
|
||||
import { REMOVAL_DRILL_SUITES_OUTSIDE_COVERAGE } from "./lib/feature-scaffold-drill.ts";
|
||||
import { REMOVABLE_TEMPLATE_FEATURES } from "./lib/removable-template-features.ts";
|
||||
import { SCAFFOLD_PROBE_FEATURE_ID } from "./lib/template-probe-features.ts";
|
||||
|
||||
/**
|
||||
* 09-07 (D-10). Removes one installed feature, `--feature=<id>`, from a copy
|
||||
@@ -163,6 +165,22 @@ const located = await locateFeature(featureId);
|
||||
const featureRouteIds = Object.entries(ROUTE_FEATURE_OWNER)
|
||||
.filter(([, owner]) => owner === featureId)
|
||||
.map(([routeId]) => routeId);
|
||||
// 0925 FOLLOW-UP 09-07. A browser test that opens the feature by one of these
|
||||
// paths is residue (scripts/lib/feature-residue.ts). A platform route the
|
||||
// feature took over (its home) goes back to the platform with the removal.
|
||||
const platformRoutePaths = new Set<string>(
|
||||
Object.values(PLATFORM_ROUTE_REGISTRY).map((route) => route.path),
|
||||
);
|
||||
const featureRoutes: FeatureRoutes = Object.freeze({
|
||||
paths: featureRouteIds.map(routePath).filter((candidate) => !platformRoutePaths.has(candidate)),
|
||||
remainingPaths: [
|
||||
...platformRoutePaths,
|
||||
...Object.keys(ROUTE_FEATURE_OWNER)
|
||||
.filter((routeId) => !featureRouteIds.includes(routeId))
|
||||
.map(routePath),
|
||||
],
|
||||
ids: featureRouteIds.filter((routeId) => !Object.hasOwn(PLATFORM_ROUTE_REGISTRY, routeId)),
|
||||
});
|
||||
|
||||
const fixtureRoot = await createRemovalFixtureRoot(`${featureId}-removal`);
|
||||
const pnpmCli = requireRemovalFixtureEnvironment("npm_execpath");
|
||||
@@ -454,11 +472,17 @@ try {
|
||||
|
||||
// 1105/16-04. Template tests use example feature IDs as data; only what
|
||||
// still points at the removed feature counts (scripts/lib/feature-residue.ts).
|
||||
const residue = await productFeatureResidue(fixtureRoot, featureId, located.directory);
|
||||
const builtResiduePattern = new RegExp(
|
||||
`${escapeRegExp(featureId)}|${escapeRegExp(located.directory)}`,
|
||||
"i",
|
||||
// 0925 FOLLOW-UP 09-07. The drill runs no Playwright spec; one that still
|
||||
// opens the feature's URL is found here instead of in FE-GATE-008.
|
||||
const residue = await productFeatureResidue(
|
||||
fixtureRoot,
|
||||
featureId,
|
||||
located.directory,
|
||||
featureRoutes,
|
||||
);
|
||||
// 1105/16-04. The same whole-name rule as `src`: the template's bundle
|
||||
// holds `data-product-feature`, which a substring search counted.
|
||||
const builtResiduePattern = featureNamePattern(featureId, located.directory);
|
||||
|
||||
const missingCommonTests: string[] = [];
|
||||
for (const testPath of commonTestPaths) {
|
||||
@@ -534,7 +558,7 @@ try {
|
||||
// 1103/09-06. With the write slice (NEVER), which needs nothing from
|
||||
// the sample either.
|
||||
const created = check("scaffold-create-feature", "create:feature", [
|
||||
"scaffold-feature",
|
||||
SCAFFOLD_PROBE_FEATURE_ID,
|
||||
"--with-create",
|
||||
]);
|
||||
checks.push(created);
|
||||
|
||||
@@ -234,6 +234,30 @@ class TurnEndNudgeTest(RepositoryTestCase):
|
||||
self.bash(command)
|
||||
self.assertIsNone(self.stop())
|
||||
|
||||
def test_reading_verify_sh_or_a_dry_run_does_not_count(self) -> None:
|
||||
# 1112/08-09. Only a command that runs a desktop step clears the reminder.
|
||||
for command in ("scripts/verify.sh merge --dry-run",
|
||||
"sed -n 1,80p scripts/verify.sh && ls",
|
||||
"grep -n foo scripts/verify.sh config/ci/gates.json",
|
||||
"git log -- scripts/verify.sh docs/work",
|
||||
"ssh desktop 'cat /tmp/claude-gates/x/FE-GATE-005.log | grep vitest'"):
|
||||
with self.subTest(command=command):
|
||||
self.edit("src/domain/order.ts", "export const a = 5;\n")
|
||||
self.bash(command)
|
||||
self.assertIsNotNone(self.stop())
|
||||
|
||||
def test_a_wrapped_desktop_step_counts(self) -> None:
|
||||
for command in ("timeout 900 scripts/verify.sh exec --log x -- node scripts/run-vitest.ts run tests/unit/a.test.ts",
|
||||
"VERIFY_SNAPSHOT=1 scripts/verify.sh merge --log r9",
|
||||
# round9 confirm review: a shell that runs the script, and ssh options with a value.
|
||||
"bash scripts/verify.sh merge --log r9",
|
||||
"ssh -o BatchMode=yes desktop 'cd ~/workspace/x && corepack pnpm -s lint'",
|
||||
"ssh -p 22 desktop 'corepack pnpm -s lint'"):
|
||||
with self.subTest(command=command):
|
||||
self.edit("src/domain/order.ts", "export const a = 6;\n")
|
||||
self.bash(command)
|
||||
self.assertIsNone(self.stop())
|
||||
|
||||
def test_laptop_commands_and_other_hosts_do_not_count(self) -> None:
|
||||
for command in ("corepack pnpm lint", "ssh build-box 'corepack pnpm lint'", "scripts/verify.sh docs",
|
||||
"scripts/verify.sh hooks", "scripts/verify.sh gate FE-GATE-005 --on here",
|
||||
@@ -244,13 +268,22 @@ class TurnEndNudgeTest(RepositoryTestCase):
|
||||
self.assertIsNotNone(self.stop())
|
||||
|
||||
def test_files_the_laptop_checks_do_not_need_the_desktop(self) -> None:
|
||||
for path in (".claude/rules/x.md", "scripts/hooks/hooks.py", "scripts/tests/test_x.py", "CLAUDE.md",
|
||||
"docs/ledger/estimates.jsonl", "scripts/check-work-docs.py", "src/adapters/AGENTS.md",
|
||||
"src/features/CLAUDE.md"):
|
||||
for path in (".claude/settings.json", "scripts/hooks/hooks.py", "scripts/tests/test_x.py",
|
||||
"docs/ledger/estimates.jsonl", "scripts/check-work-docs.py"):
|
||||
self.repo.write(path, "x\n")
|
||||
run_event("post-edit", self.repo.payload(path))
|
||||
self.assertIsNone(self.stop())
|
||||
|
||||
def test_living_instruction_documents_need_the_desktop(self) -> None:
|
||||
# 1112/08-04. verify:documentation, a desktop gate, checks these documents too.
|
||||
for path in (".claude/rules/x.md", ".claude/skills/fe-x/SKILL.md", "CLAUDE.md",
|
||||
"src/adapters/AGENTS.md", "src/features/CLAUDE.md",
|
||||
# round9 confirm review: living module READMEs beside laptop-checked files.
|
||||
"scripts/hooks/README.md", "docs/ledger/README.md"):
|
||||
with self.subTest(path=path):
|
||||
self.edit(path, "x\n")
|
||||
self.assertIsNotNone(self.stop())
|
||||
|
||||
def test_a_new_edit_after_the_reminder_reminds_again(self) -> None:
|
||||
self.edit("src/domain/order.ts", "export const a = 4;\n")
|
||||
self.stop()
|
||||
|
||||
@@ -90,6 +90,45 @@ class StagePlanTest(unittest.TestCase):
|
||||
expected.append(" ".join(words))
|
||||
self.assertEqual([line.split(": ", 1)[1] for line in result.stdout.splitlines()], expected)
|
||||
|
||||
def test_parts_passes_a_negative_fixture_only_with_its_registered_diagnostic(self) -> None:
|
||||
# run-ci-gate.ts passes an expect=fail command only when it exits with its code and prints its
|
||||
# diagnostic. parts saw the exit code alone, so a checker broken into an unrelated exit 1 (a
|
||||
# TypeError) still counted as its negative fixture passing.
|
||||
contract = gates()
|
||||
commands = {c["id"]: c for c in contract["commands"]}
|
||||
gate = next(g for g in contract["gates"] if g["id"] == "FE-GATE-029")
|
||||
negatives = [commands[c] for c in gate["commandIds"] if commands[c].get("expect") == "fail"]
|
||||
self.assertTrue(any(c.get("expectedDiagnosticId") for c in negatives))
|
||||
with tempfile.TemporaryDirectory() as tmp:
|
||||
fake = Path(tmp) / "corepack"
|
||||
# Answers `corepack pnpm -s <script> ...args` as the contract registers that command:
|
||||
# pass commands exit 0, negative fixtures exit with their code and print DIAGNOSTIC_MODE.
|
||||
fake.write_text(f"""#!/usr/bin/env python3
|
||||
import json, os, sys
|
||||
script, args = sys.argv[3], sys.argv[4:]
|
||||
for command in json.load(open({str(REPO / "config/ci/gates.json")!r}))["commands"]:
|
||||
if command["script"] == script and command.get("args", []) == args:
|
||||
break
|
||||
else:
|
||||
sys.exit(97)
|
||||
if command.get("expect") != "fail":
|
||||
sys.exit(0)
|
||||
if os.environ["DIAGNOSTIC_MODE"] == "registered":
|
||||
print("checker refused the fixture:", command.get("expectedDiagnosticId", ""))
|
||||
else:
|
||||
print("TypeError: Cannot read properties of undefined")
|
||||
sys.exit(command.get("expectedExitCode", 1))
|
||||
""", encoding="utf-8")
|
||||
fake.chmod(0o755)
|
||||
env = {"PATH": f"{tmp}:{os.environ['PATH']}"}
|
||||
wrong = sh([str(VERIFY), "parts", "FE-GATE-029", "--on", "here"], cwd=REPO, check=False,
|
||||
env={**env, "DIAGNOSTIC_MODE": "unrelated"})
|
||||
self.assertEqual(wrong.returncode, 1, wrong.stdout + wrong.stderr)
|
||||
self.assertIn("diagnostic", wrong.stderr)
|
||||
right = sh([str(VERIFY), "parts", "FE-GATE-029", "--on", "here"], cwd=REPO, check=False,
|
||||
env={**env, "DIAGNOSTIC_MODE": "registered"})
|
||||
self.assertEqual(right.returncode, 0, right.stdout + right.stderr)
|
||||
|
||||
def test_arguments_after_the_separator_go_to_the_one_script_or_command_as_given(self) -> None:
|
||||
result = sh([str(VERIFY), "script", "test:sample-removal", "--dry-run", "--", "--feature=invoice-feature"],
|
||||
cwd=REPO)
|
||||
|
||||
@@ -131,7 +131,20 @@ if (liveTarget?.passed && !slotEmpty) {
|
||||
const fixture = await readDocument(
|
||||
"tests/fixtures/hosting/response-headers.json",
|
||||
);
|
||||
responses = responseHeaders(fixture.responses);
|
||||
// 0929/13-04. The fixture host answers with the declared security headers
|
||||
// wherever the fixture names none, so a policy change is one file. A value
|
||||
// the fixture names is compared like a host's answer.
|
||||
const declaredAnswer = Object.fromEntries(
|
||||
Object.entries(securityHeaders).map(([header, value]) => [header.toLowerCase(), value]),
|
||||
);
|
||||
responses = Object.fromEntries(
|
||||
Object.entries(responseHeaders(fixture.responses)).map(([surface, headers]) => [
|
||||
surface,
|
||||
recordValue(cacheSurfaces[surface]).securityHeaders === true
|
||||
? { ...declaredAnswer, ...headers }
|
||||
: headers,
|
||||
]),
|
||||
);
|
||||
}
|
||||
|
||||
const results: ProbeResult[] = [...probeResults];
|
||||
|
||||
+32
-8
@@ -70,7 +70,8 @@ elif kind == "scripts":
|
||||
command = commands[command_id]
|
||||
# \x1f between fields keeps an empty exit code a field; \x1e between the command's args.
|
||||
args = "\x1e".join(command.get("args", []))
|
||||
print(f'{command["script"]}\x1f{command.get("expect", "pass")}\x1f{command.get("expectedExitCode", "")}\x1f{args}')
|
||||
print(f'{command["script"]}\x1f{command.get("expect", "pass")}\x1f{command.get("expectedExitCode", "")}'
|
||||
f'\x1f{args}\x1f{command.get("expectedDiagnosticId", "")}')
|
||||
PY
|
||||
}
|
||||
|
||||
@@ -119,8 +120,18 @@ step() {
|
||||
start=$(date +%s)
|
||||
log=${VERIFY_STEP_LOGS:+$VERIFY_STEP_LOGS/$(printf '%s' "$name" | tr ' /:' '___').log}
|
||||
set +e
|
||||
if [ -n "$log" ]; then "$@" > "$log" 2>&1; else "$@"; fi
|
||||
rc=$?
|
||||
# STEP_CAPTURE: also keep the output in that file (run_parts reads a negative fixture's diagnostic).
|
||||
if [ -n "$log" ]; then
|
||||
"$@" > "$log" 2>&1
|
||||
rc=$?
|
||||
[ -z "${STEP_CAPTURE:-}" ] || cp "$log" "$STEP_CAPTURE"
|
||||
elif [ -n "${STEP_CAPTURE:-}" ]; then
|
||||
"$@" 2>&1 | tee "$STEP_CAPTURE"
|
||||
rc=${PIPESTATUS[0]}
|
||||
else
|
||||
"$@"
|
||||
rc=$?
|
||||
fi
|
||||
set -e
|
||||
echo "$name rc=$rc $(( $(date +%s) - start ))s" | tee -a "${VERIFY_SUMMARY:-/dev/null}"
|
||||
return "$rc"
|
||||
@@ -148,20 +159,33 @@ run_gates() {
|
||||
}
|
||||
|
||||
run_parts() {
|
||||
local gate=$1 failed=0 script expect code argtext rc args prefix
|
||||
local gate=$1 failed=0 script expect code argtext diagnostic rc args prefix capture
|
||||
[ "$DRY_RUN" = 1 ] || ci_env
|
||||
gates_json scripts "$gate" > /dev/null || { echo "verify: config/ci/gates.json에 없는 게이트: $gate" >&2; return 2; }
|
||||
prefix=$(host_prefix "$gate")
|
||||
while IFS=$'\x1f' read -r script expect code argtext; do
|
||||
while IFS=$'\x1f' read -r script expect code argtext diagnostic; do
|
||||
rc=0
|
||||
args=()
|
||||
# The command's args, as run-ci-gate.ts passes them (`pnpm <script> ...args`).
|
||||
[ -z "$argtext" ] || IFS=$'\x1e' read -r -a args <<< "$argtext"
|
||||
capture=""
|
||||
if [ "$expect" = fail ] && [ "$DRY_RUN" != 1 ]; then
|
||||
capture=$(mktemp)
|
||||
TMP_FILES+=("$capture")
|
||||
fi
|
||||
# shellcheck disable=SC2086
|
||||
step "$gate $script" $prefix corepack pnpm -s "$script" ${args[@]+"${args[@]}"} || rc=$?
|
||||
# expect=fail인 명령(음성 fixture)은 정해진 종료 코드로 실패해야 통과다.
|
||||
STEP_CAPTURE=$capture step "$gate $script" $prefix corepack pnpm -s "$script" ${args[@]+"${args[@]}"} || rc=$?
|
||||
# expect=fail인 명령(음성 fixture)은 run-ci-gate.ts처럼 정해진 종료 코드로 실패하고 정해진 진단 문구를
|
||||
# 출력해야 통과다. 종료 코드만 보면 엉뚱한 원인의 exit 1(깨진 검사기)도 통과로 센다.
|
||||
if [ "$expect" = fail ]; then
|
||||
[ "$DRY_RUN" = 1 ] || [ "$rc" = "${code:-1}" ] || failed=1
|
||||
[ "$DRY_RUN" = 1 ] && continue
|
||||
if [ "$rc" != "${code:-1}" ]; then
|
||||
echo "verify: $gate $script: expected exit ${code:-1}, got $rc" >&2
|
||||
failed=1
|
||||
elif [ -n "$diagnostic" ] && ! grep -qF -- "$diagnostic" "$capture"; then
|
||||
echo "verify: $gate $script: exit $rc without the registered diagnostic: $diagnostic" >&2
|
||||
failed=1
|
||||
fi
|
||||
elif [ "$rc" != 0 ]; then
|
||||
failed=1
|
||||
fi
|
||||
|
||||
@@ -311,6 +311,7 @@ export function createFeatureHttpBinding<
|
||||
contract.contract.responseEnvelope === "ENVELOPE_V1",
|
||||
),
|
||||
outcome,
|
||||
contract.contract.responseEnvelope === "ENVELOPE_V1",
|
||||
);
|
||||
},
|
||||
});
|
||||
@@ -345,10 +346,18 @@ function envelopeProblemMapping(
|
||||
problem: unknown,
|
||||
status: number,
|
||||
): FeatureHttpProblemMapping | undefined {
|
||||
const code = envelopeCode(problem);
|
||||
if (code === undefined) return undefined;
|
||||
const { details } = problem as Readonly<Record<string, unknown>>;
|
||||
return envelopeFailureReading(status, { code, details });
|
||||
}
|
||||
|
||||
/** The backend `error.code` of an Envelope problem, when it is well formed. */
|
||||
function envelopeCode(problem: unknown): string | undefined {
|
||||
if (!problem || typeof problem !== "object") return undefined;
|
||||
const { code, details } = problem as Readonly<Record<string, unknown>>;
|
||||
const { code } = problem as Readonly<Record<string, unknown>>;
|
||||
return typeof code === "string" && /^[A-Z0-9_]{1,64}$/u.test(code)
|
||||
? envelopeFailureReading(status, { code, details })
|
||||
? code
|
||||
: undefined;
|
||||
}
|
||||
|
||||
@@ -358,6 +367,8 @@ function envelopeProblemMapping(
|
||||
* 0929/03-04. Without an echo (timeout, lost connection, a gateway that drops
|
||||
* the header) it is the id the request carried.
|
||||
* 1103/03-06. A failure Envelope's `meta.traceId` becomes `traceId`.
|
||||
* 1112/01-06. An Envelope operation's problem keeps the backend's own code as
|
||||
* `backendCode`, whatever code the feature mapped it to.
|
||||
*/
|
||||
function projectExecutionOutcome<WireOutput, Problem, Value>(
|
||||
operationId: string,
|
||||
@@ -372,8 +383,15 @@ function projectExecutionOutcome<WireOutput, Problem, Value>(
|
||||
) => FeatureHttpProblemMapping | undefined)
|
||||
| undefined,
|
||||
outcome: HttpExecutionOutcome<WireOutput, Problem>,
|
||||
enveloped: boolean,
|
||||
): Result<Value, AppFailure> {
|
||||
const projected = projectOutcome(operationId, mapSuccess, mapProblem, outcome);
|
||||
const projected = projectOutcome(
|
||||
operationId,
|
||||
mapSuccess,
|
||||
mapProblem,
|
||||
outcome,
|
||||
enveloped,
|
||||
);
|
||||
const metadata = "metadata" in outcome ? outcome.metadata : undefined;
|
||||
const requestId = metadata?.correlationReference ?? outcome.sentRequestId;
|
||||
const traceId = metadata?.traceReference;
|
||||
@@ -402,6 +420,7 @@ function projectOutcome<WireOutput, Problem, Value>(
|
||||
) => FeatureHttpProblemMapping | undefined)
|
||||
| undefined,
|
||||
outcome: HttpExecutionOutcome<WireOutput, Problem>,
|
||||
enveloped: boolean,
|
||||
): Result<Value, AppFailure> {
|
||||
// A throwing feature mapper is a mapping defect, not a transport failure: it
|
||||
// must not reject and lose the effect the server already confirmed.
|
||||
@@ -444,11 +463,13 @@ function projectOutcome<WireOutput, Problem, Value>(
|
||||
} catch {
|
||||
return mapperThrew(outcome.effect, outcome.metadata.status);
|
||||
}
|
||||
const backendCode = enveloped ? envelopeCode(outcome.problem) : undefined;
|
||||
return failure(
|
||||
mapped?.kind ?? kindForStatus(outcome.metadata.status),
|
||||
operationId,
|
||||
mapped?.code ?? "CONTRACT_PROBLEM",
|
||||
{
|
||||
...(backendCode === undefined ? {} : { backendCode }),
|
||||
httpStatus: outcome.metadata.status,
|
||||
// 백엔드 1101/02-01. A resend of an unknown answer waits on it.
|
||||
...(outcome.metadata.retryAfterMs === undefined
|
||||
@@ -578,6 +599,7 @@ function failure(
|
||||
operationId: string,
|
||||
code: string,
|
||||
details: Readonly<{
|
||||
backendCode?: string;
|
||||
httpStatus?: number;
|
||||
retryAfterMs?: number;
|
||||
effect?: FailureEffectCertainty;
|
||||
|
||||
@@ -117,7 +117,8 @@ export type BoundedPollCoordinatorDependencies<
|
||||
* (the V3 executor returns a rejected fetch as NETWORK_FAILURE). A throw,
|
||||
* like a result of the wrong shape, ends the lease with PROTOCOL_MISMATCH
|
||||
* and is not retried: it is a composition defect, not a server outage.
|
||||
* Design 9.2 maps each V3 executor outcome to a result.
|
||||
* docs/architecture/optional-adapter-recipes.md 「poll attempt 결과 대응」
|
||||
* maps each V3 executor outcome to a result.
|
||||
*/
|
||||
execute(input: Readonly<{
|
||||
operationId: string;
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# AGENTS.md — `src/contracts` (공유 어휘와 레지스트리)
|
||||
|
||||
여러 계층, worker, 빌드·릴리스 스크립트가 함께 읽는 타입·스키마·레지스트리다. 공유 타입을 어디 둘지는 `docs/architecture/contract-ownership.md` 「Decision rule」이다.
|
||||
여러 계층, worker, 빌드·릴리스 스크립트가 함께 읽는 타입·스키마·레지스트리다. 공유 타입을 어디 둘지는 `docs/architecture/contract-ownership.md` 「판단 규칙」이다.
|
||||
|
||||
## 지킬 것
|
||||
|
||||
@@ -13,5 +13,5 @@
|
||||
|
||||
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
|
||||
- `check:registries`(FE-GATE-010 안), `test:runtime-schema`(FE-GATE-004)
|
||||
- 짝 백엔드 계약 pin `config/contracts/backend-contract-pin.json`과 대조 테스트(FE-GATE-007)
|
||||
- 짝 백엔드 계약 pin `config/contracts/backend-contract-pin.json`과 대조 테스트(FE-GATE-005의 `tests/unit/backend-contract-pin.test.ts`·`backend-contract-pin-document.test.ts`, FE-GATE-007의 `tests/integration/fileserver-upload.test.ts`)
|
||||
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/runtime-schema`, `tests/unit`에 둔다(`.claude/rules/tests.md`).
|
||||
|
||||
+28
-3
@@ -130,6 +130,13 @@ export type FailureEffectCertainty =
|
||||
export type AppFailure = Readonly<{
|
||||
kind: FailureKind;
|
||||
code: string;
|
||||
/**
|
||||
* 1112/01-06. The code the paired backend's Envelope carried, as it came:
|
||||
* a feature's `mapProblem` may change `code`, never this. Only the HTTP
|
||||
* binding sets it, for an `ENVELOPE_V1` operation's problem; elsewhere it
|
||||
* is absent.
|
||||
*/
|
||||
backendCode?: string;
|
||||
httpStatus?: number;
|
||||
/**
|
||||
* Whether sending the same operation again is safe as far as this failure
|
||||
@@ -164,6 +171,7 @@ export type ApiFailure = AppFailure;
|
||||
|
||||
export type FailureDetails = Readonly<{
|
||||
code?: string;
|
||||
backendCode?: string;
|
||||
httpStatus?: number;
|
||||
requestId?: string;
|
||||
traceId?: string;
|
||||
@@ -183,6 +191,9 @@ export function createFailure(
|
||||
return Object.freeze({
|
||||
kind: definition.kind,
|
||||
code: typeof details.code === "string" ? details.code : definition.kind,
|
||||
...(typeof details.backendCode === "string"
|
||||
? { backendCode: details.backendCode }
|
||||
: {}),
|
||||
retryable:
|
||||
details.effect === "MAYBE_APPLIED" ||
|
||||
details.effect === "APPLIED_CONFIRMED"
|
||||
@@ -259,6 +270,16 @@ export const REFUSALS_OF_EVERY_ATTEMPT: Readonly<Record<string, number>> =
|
||||
IDEMPOTENCY_KEY_INVALID: 400,
|
||||
});
|
||||
|
||||
/**
|
||||
* 1112/01-03. The request did not fail: its caller aborted it
|
||||
* (`REQUEST_ABORTED`) or a scope fence ended it (`SCOPE_GENERATION_CHANGED`,
|
||||
* sign-out or account switch). Telemetry and terminal error screens do not
|
||||
* count it (testing strategy 7.1절).
|
||||
*/
|
||||
export function isAbortFailure(failure: AppFailure): boolean {
|
||||
return failure.kind === "REQUEST_ABORTED" || failure.kind === "SCOPE_GENERATION_CHANGED";
|
||||
}
|
||||
|
||||
/**
|
||||
* 1106/03-01 (D10 supplement and its second fix). A `NOT_APPLIED` refusal
|
||||
* the same request gets on every attempt: a row above, code and status
|
||||
@@ -268,13 +289,17 @@ export const REFUSALS_OF_EVERY_ATTEMPT: Readonly<Record<string, number>> =
|
||||
* 403, 503 RATE_LIMIT_*), a code a feature declared refused before its
|
||||
* write (it may be a rule on changing state), any other code, and
|
||||
* `NOT_STARTED`. The kind is not read: a feature's `mapProblem` sets it, and
|
||||
* it maps its own codes, or every 422, to `VALIDATION_REJECTED`.
|
||||
* it maps its own codes, or every 422, to `VALIDATION_REJECTED`. 1112/01-06.
|
||||
* Nor is `code`, for the same reason: the answer is `backendCode`, the code
|
||||
* the backend's Envelope carried. A failure without it is not settled.
|
||||
*/
|
||||
export function isRefusedOnEveryAttempt(failure: AppFailure): boolean {
|
||||
if (failure.effect !== "NOT_APPLIED") return false;
|
||||
const code = failure.backendCode;
|
||||
return (
|
||||
Object.hasOwn(REFUSALS_OF_EVERY_ATTEMPT, failure.code) &&
|
||||
REFUSALS_OF_EVERY_ATTEMPT[failure.code] === failure.httpStatus
|
||||
code !== undefined &&
|
||||
Object.hasOwn(REFUSALS_OF_EVERY_ATTEMPT, code) &&
|
||||
REFUSALS_OF_EVERY_ATTEMPT[code] === failure.httpStatus
|
||||
);
|
||||
}
|
||||
|
||||
|
||||
@@ -53,11 +53,17 @@ export type ApplicationResult<Value> = Result<Value>;
|
||||
|
||||
class ApplicationQueryError extends Error {
|
||||
readonly failure: AppFailure;
|
||||
/**
|
||||
* 1112/01-04. What the cache diagnostics record (`safeErrorKind` reads
|
||||
* `kind` first): the failure's kind, not one name for every failure.
|
||||
*/
|
||||
readonly kind: AppFailure["kind"];
|
||||
|
||||
constructor(failure: AppFailure) {
|
||||
super(failure.kind);
|
||||
this.name = "ApplicationQueryError";
|
||||
this.failure = failure;
|
||||
this.kind = failure.kind;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -100,7 +106,6 @@ export function useApplicationQuery<Value>(
|
||||
"definitionId" in options ? options.definitionId : "APPLICATION_QUERY";
|
||||
const invalidation =
|
||||
"invalidation" in options ? options.invalidation : undefined;
|
||||
const [staleFailure, setStaleFailure] = useState(false);
|
||||
useEffect(() => {
|
||||
identity?.acquire();
|
||||
return () => identity?.release();
|
||||
@@ -170,9 +175,10 @@ export function useApplicationQuery<Value>(
|
||||
throw new DOMException("Query cancelled", "AbortError");
|
||||
}
|
||||
if (error instanceof ApplicationQueryError) throw error;
|
||||
// 1112/01-04. The definition it came from, as the other failures here.
|
||||
throw new ApplicationQueryError(
|
||||
normalizeUnknownFailure(error, {
|
||||
operationId: "APPLICATION_QUERY",
|
||||
operationId: queryDefinitionId,
|
||||
}),
|
||||
);
|
||||
} finally {
|
||||
@@ -181,17 +187,13 @@ export function useApplicationQuery<Value>(
|
||||
},
|
||||
});
|
||||
const hasData = query.data !== undefined && query.data !== null;
|
||||
|
||||
useEffect(() => {
|
||||
if (query.isError && hasData) {
|
||||
setStaleFailure(true);
|
||||
} else if (query.isSuccess && !query.isFetching) {
|
||||
setStaleFailure(false);
|
||||
}
|
||||
}, [hasData, query.isError, query.isFetching, query.isSuccess]);
|
||||
// 1112/01-05. Read while rendering: the data is stale because the last
|
||||
// fetch failed, and no fetch runs now. A retry that is running shows as
|
||||
// refreshing; copied into state by an effect, the old failure came back
|
||||
// over the retry's reset.
|
||||
const staleFailure = query.isError && hasData && !query.isFetching;
|
||||
|
||||
const retry = useCallback(async () => {
|
||||
setStaleFailure(false);
|
||||
await query.refetch({ cancelRefetch: false });
|
||||
}, [query]);
|
||||
|
||||
@@ -368,6 +370,12 @@ export function useApplicationMutation<Input, Value>(
|
||||
"definitionId" in options
|
||||
? options.definitionId ?? "LEGACY_MUTATION"
|
||||
: "LEGACY_MUTATION";
|
||||
// 1112/01-04. An unexpected throw names the mutation definition it came
|
||||
// from; a legacy mutation without one keeps the generic name.
|
||||
const failureOperationId =
|
||||
"definitionId" in options && options.definitionId
|
||||
? options.definitionId
|
||||
: "APPLICATION_MUTATION";
|
||||
const definitionVersion =
|
||||
"definitionVersion" in options ? options.definitionVersion : 0;
|
||||
const duplicatePolicy =
|
||||
@@ -701,7 +709,7 @@ export function useApplicationMutation<Input, Value>(
|
||||
error instanceof ApplicationQueryError
|
||||
? error.failure
|
||||
: normalizeUnknownFailure(error, {
|
||||
operationId: "APPLICATION_MUTATION",
|
||||
operationId: failureOperationId,
|
||||
});
|
||||
const failure = mutationFailureWithEffect(reportedFailure);
|
||||
switch (failure.effect) {
|
||||
@@ -758,7 +766,7 @@ export function useApplicationMutation<Input, Value>(
|
||||
.catch((error: unknown) => {
|
||||
const failure = withFailureEffect(
|
||||
normalizeUnknownFailure(error, {
|
||||
operationId: "APPLICATION_MUTATION",
|
||||
operationId: failureOperationId,
|
||||
}),
|
||||
"NOT_STARTED",
|
||||
);
|
||||
@@ -794,6 +802,7 @@ export function useApplicationMutation<Input, Value>(
|
||||
queryClient,
|
||||
definitionId,
|
||||
duplicatePolicy,
|
||||
failureOperationId,
|
||||
mutationIntentFactory,
|
||||
mutationOperationId,
|
||||
requiresIdempotencyKey,
|
||||
|
||||
@@ -818,6 +818,7 @@ describe("application mutation intent admission", () => {
|
||||
"400 VALIDATION_FAILED with its field list",
|
||||
createFailure("VALIDATION_REJECTED", "CREATE_REPLAYED", 0, {
|
||||
code: "VALIDATION_FAILED",
|
||||
backendCode: "VALIDATION_FAILED",
|
||||
httpStatus: 400,
|
||||
effect: "NOT_APPLIED",
|
||||
}),
|
||||
@@ -826,6 +827,7 @@ describe("application mutation intent admission", () => {
|
||||
"400 VALIDATION_FAILED whose body did not parse",
|
||||
createFailure("UNKNOWN_CLIENT_FAILURE", "CREATE_REPLAYED", 0, {
|
||||
code: "VALIDATION_FAILED",
|
||||
backendCode: "VALIDATION_FAILED",
|
||||
httpStatus: 400,
|
||||
effect: "NOT_APPLIED",
|
||||
}),
|
||||
@@ -834,6 +836,7 @@ describe("application mutation intent admission", () => {
|
||||
"400 IDEMPOTENCY_KEY_INVALID",
|
||||
createFailure("UNKNOWN_CLIENT_FAILURE", "CREATE_REPLAYED", 0, {
|
||||
code: "IDEMPOTENCY_KEY_INVALID",
|
||||
backendCode: "IDEMPOTENCY_KEY_INVALID",
|
||||
httpStatus: 400,
|
||||
effect: "NOT_APPLIED",
|
||||
}),
|
||||
@@ -883,6 +886,7 @@ describe("application mutation intent admission", () => {
|
||||
"refused with 400 VALIDATION_FAILED",
|
||||
createFailure("VALIDATION_REJECTED", "CREATE_REPLAYED", 0, {
|
||||
code: "VALIDATION_FAILED",
|
||||
backendCode: "VALIDATION_FAILED",
|
||||
httpStatus: 400,
|
||||
effect: "NOT_APPLIED",
|
||||
}),
|
||||
|
||||
@@ -8,6 +8,7 @@ import {
|
||||
type ApplicationResult,
|
||||
useApplicationQuery,
|
||||
} from "../../src/presentation/adapters/query/application-query.ts";
|
||||
import { createQueryClient } from "../../src/adapters/query-cache/index.ts";
|
||||
import { createFailure } from "../../src/contracts/errors.ts";
|
||||
import { queryClient, wrapper } from "./application-query-fixture.tsx";
|
||||
|
||||
@@ -250,5 +251,75 @@ describe("application query inbound bridge", () => {
|
||||
await waitFor(() => expect(aborted).toBe(true));
|
||||
expect(client.getQueryState(["cancelled"])?.status).not.toBe("error");
|
||||
});
|
||||
});
|
||||
|
||||
// 1112/01-05. Whether stale data failed is the query's own state, read
|
||||
// while rendering. Copied into state by an effect, it came back over the
|
||||
// retry's reset, so a retry of stale data still said the old failure.
|
||||
it("shows a retry of stale data as refreshing, not as the old failure", async () => {
|
||||
const client = queryClient();
|
||||
let release: ((value: ApplicationResult<string[]>) => void) | undefined;
|
||||
const execute = vi
|
||||
.fn<() => Promise<ApplicationResult<string[]>>>()
|
||||
.mockResolvedValueOnce({ ok: true, value: ["first"] })
|
||||
.mockResolvedValueOnce({ ok: false, error: createFailure("SERVER_FAILURE", "LIST", 0) })
|
||||
.mockImplementationOnce(
|
||||
() => new Promise((resolve) => {
|
||||
release = resolve;
|
||||
}),
|
||||
);
|
||||
const hook = renderHook(
|
||||
() => useApplicationQuery({ queryKey: ["resource", "stale-retry"], execute }),
|
||||
{ wrapper: wrapper(client) },
|
||||
);
|
||||
await waitFor(() => expect(hook.result.current.data).toEqual(["first"]));
|
||||
await act(() => hook.result.current.retry());
|
||||
await waitFor(() => expect(hook.result.current.state.indicator).toBe("stale-degraded"));
|
||||
|
||||
act(() => {
|
||||
void hook.result.current.retry();
|
||||
});
|
||||
|
||||
await waitFor(() => expect(hook.result.current.state.indicator).toBe("refreshing"));
|
||||
await act(async () => release?.({ ok: true, value: ["recovered"] }));
|
||||
await waitFor(() => expect(hook.result.current.state.indicator).toBeNull());
|
||||
});
|
||||
|
||||
// 1112/01-04. A failed query or mutation was recorded as one kind,
|
||||
// APPLICATION_QUERY_ERROR, whatever it was; an unexpected throw lost the
|
||||
// definition it came from.
|
||||
it("names the failure's kind in the cache diagnostics", async () => {
|
||||
const record = vi.fn();
|
||||
const client = createQueryClient({ diagnostics: { record } });
|
||||
renderHook(
|
||||
() =>
|
||||
useApplicationQuery({
|
||||
queryKey: ["resource", "missing"],
|
||||
execute: async () => ({ ok: false, error: createFailure("NOT_FOUND", "GET", 0) }),
|
||||
}),
|
||||
{ wrapper: wrapper(client) },
|
||||
);
|
||||
|
||||
await waitFor(() => expect(record).toHaveBeenCalled());
|
||||
expect(record.mock.calls[0]?.[0]).toMatchObject({
|
||||
eventId: "cache.operation.failed",
|
||||
context: { operation: "query", error_kind: "NOT_FOUND" },
|
||||
});
|
||||
});
|
||||
|
||||
it("names the query definition of an unexpected throw", async () => {
|
||||
const hook = renderHook(
|
||||
() =>
|
||||
useApplicationQuery({
|
||||
queryKey: ["resource", "throws"],
|
||||
definitionId: "resource-list-v1",
|
||||
execute: async () => {
|
||||
throw new Error("boom");
|
||||
},
|
||||
} as Parameters<typeof useApplicationQuery<string[]>>[0]),
|
||||
{ wrapper: wrapper(queryClient()) },
|
||||
);
|
||||
|
||||
await waitFor(() => expect(hook.result.current.state.failure).toBeDefined());
|
||||
expect(hook.result.current.state.failure?.operationId).toBe("resource-list-v1");
|
||||
});
|
||||
});
|
||||
|
||||
@@ -309,4 +309,61 @@ describe("feature HTTP binding", () => {
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
// 1112/01-06. An Envelope operation's failure keeps the backend's own code
|
||||
// next to the one the feature mapped, so the resend decision reads the
|
||||
// answer the backend gave.
|
||||
it("keeps the backend's Envelope code when the feature maps it to another", async () => {
|
||||
const enveloped = Object.freeze({
|
||||
LOAD_RESOURCE: defineFeatureHttpOperation({
|
||||
contract: Object.freeze({
|
||||
...LOAD_RESOURCE_CONTRACT,
|
||||
contract: Object.freeze({
|
||||
...LOAD_RESOURCE_CONTRACT.contract,
|
||||
responseEnvelope: "ENVELOPE_V1" as const,
|
||||
}),
|
||||
}),
|
||||
routeId: "RESOURCE_DETAIL",
|
||||
mapSuccess: (value: ResourceWire) => mappingSuccess(value),
|
||||
mapProblem: () => Object.freeze({ kind: "VALIDATION_REJECTED" as const, code: "VALIDATION_FAILED" }),
|
||||
}),
|
||||
} as const);
|
||||
const scripted = scriptedExecutor<ResourceWire, ResourceProblem>(
|
||||
Object.freeze({
|
||||
kind: "PROBLEM" as const,
|
||||
problem: Object.freeze({ code: "WORKLOG_INVALID" }),
|
||||
metadata: Object.freeze({ status: 400 }),
|
||||
effect: "NOT_APPLIED" as const,
|
||||
}),
|
||||
);
|
||||
|
||||
const result = await createFeatureHttpBinding(scripted.executor, enveloped).execute(
|
||||
"LOAD_RESOURCE",
|
||||
{ resourceId: "resource-1" },
|
||||
);
|
||||
|
||||
expect(result).toMatchObject({
|
||||
ok: false,
|
||||
error: { code: "VALIDATION_FAILED", backendCode: "WORKLOG_INVALID" },
|
||||
});
|
||||
});
|
||||
|
||||
it("gives no backend code to an operation without an Envelope", async () => {
|
||||
const scripted = scriptedExecutor<ResourceWire, ResourceProblem>(
|
||||
Object.freeze({
|
||||
kind: "PROBLEM" as const,
|
||||
problem: Object.freeze({ code: "RESOURCE_NAME_EXISTS" }),
|
||||
metadata: Object.freeze({ status: 409 }),
|
||||
effect: "NOT_APPLIED" as const,
|
||||
}),
|
||||
);
|
||||
|
||||
const result = await createFeatureHttpBinding(scripted.executor, OPERATIONS).execute(
|
||||
"LOAD_RESOURCE",
|
||||
{ resourceId: "resource-1" },
|
||||
);
|
||||
|
||||
expect(result.ok).toBe(false);
|
||||
expect(result.ok ? undefined : result.error.backendCode).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
@@ -9,8 +9,9 @@ import {
|
||||
answerInstalledApiRequest,
|
||||
type InstalledApiAnswer,
|
||||
} from "./support/installed-api-answers.ts";
|
||||
import { WCAG_AXE_TAGS } from "../support/browser/axe-tags.ts";
|
||||
|
||||
const WCAG_TAGS = ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"];
|
||||
const WCAG_TAGS = [...WCAG_AXE_TAGS];
|
||||
const SIGN_IN_TITLE = KO_MESSAGES["route.auth.required.title"];
|
||||
const CATALOG = KO_MESSAGES as Readonly<Record<string, string>>;
|
||||
|
||||
@@ -127,11 +128,23 @@ test("@a11y skip link moves keyboard focus into main", async ({ page }) => {
|
||||
.toBe(true);
|
||||
});
|
||||
|
||||
// 1112/05-08. The policy is the reduced-motion rule (responsive.css): every
|
||||
// animation and transition becomes 0.01 ms. The browser default is 0s, so the
|
||||
// check reads the rule's own value and compares it with the default, or a
|
||||
// deleted rule passes.
|
||||
test("@a11y reduced-motion policy disables long animation", async ({ page }) => {
|
||||
await page.emulateMedia({ reducedMotion: "reduce" });
|
||||
const durations = () =>
|
||||
page.locator("body").evaluate((body) => {
|
||||
const style = getComputedStyle(body);
|
||||
return [style.animationDuration, style.transitionDuration];
|
||||
});
|
||||
const REDUCED = ["0.00001s", "1e-05s"];
|
||||
await page.goto("/");
|
||||
const duration = await page
|
||||
.locator("body")
|
||||
.evaluate((body) => getComputedStyle(body).animationDuration);
|
||||
expect(["0s", "0.00001s", "1e-05s"]).toContain(duration);
|
||||
expect(await durations()).toEqual(["0s", "0s"]);
|
||||
|
||||
await page.emulateMedia({ reducedMotion: "reduce" });
|
||||
|
||||
const [animation, transition] = await durations();
|
||||
expect(REDUCED).toContain(animation);
|
||||
expect(REDUCED).toContain(transition);
|
||||
});
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
import AxeBuilder from "@axe-core/playwright";
|
||||
import type { Page, Route } from "@playwright/test";
|
||||
import { WCAG_AXE_TAGS } from "../support/browser/axe-tags.ts";
|
||||
|
||||
import { KO_MESSAGES } from "../../src/presentation/i18n/catalog.ts";
|
||||
import { expect, test } from "../support/browser/strict-browser-test.ts";
|
||||
@@ -11,6 +12,7 @@ import {
|
||||
import {
|
||||
addGeneratedFeature,
|
||||
generatedFeature,
|
||||
generatedMessageKey,
|
||||
routePath,
|
||||
type GeneratedFeature,
|
||||
} from "../../scripts/lib/generated-feature.ts";
|
||||
@@ -28,7 +30,7 @@ import { startBuildServer } from "./support/service-worker-builds.ts";
|
||||
*/
|
||||
const META = Object.freeze({ requestId: "req-e2e", traceId: "0af7651916cd43dd8448eb211c80319c" });
|
||||
const ITEM = Object.freeze({ id: "browser-order", name: "Browser order" });
|
||||
const WCAG_TAGS = ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"];
|
||||
const WCAG_TAGS = [...WCAG_AXE_TAGS];
|
||||
|
||||
let builds: FixtureBuilds<"a"> | undefined;
|
||||
let server: Awaited<ReturnType<typeof startBuildServer>> | undefined;
|
||||
@@ -59,10 +61,17 @@ function envelope(data: unknown) {
|
||||
return { success: true, data, meta: META };
|
||||
}
|
||||
|
||||
function failure(code: string, retryable: boolean) {
|
||||
/**
|
||||
* 1112/03-09. The paired backend's failure Envelope: code, category and
|
||||
* retryable as its OperationalError row gives them
|
||||
* (clean-architecture-backend-template src/shared-contract/.../OperationalError.java:
|
||||
* RATE_LIMIT_EXCEEDED is RATE_LIMIT, 429, retryable; INTERNAL_ERROR is
|
||||
* INTERNAL, 500, not retryable).
|
||||
*/
|
||||
function failure(code: string, category: string, retryable: boolean) {
|
||||
return {
|
||||
success: false,
|
||||
error: { code, category: "SYSTEM", message: "backend message", retryable },
|
||||
error: { code, category, message: "backend message", retryable },
|
||||
meta: META,
|
||||
};
|
||||
}
|
||||
@@ -122,10 +131,10 @@ async function signInAt(page: Page, path: string, heading: string) {
|
||||
await expect(page.getByRole("heading", { level: 1 })).toHaveText(heading);
|
||||
}
|
||||
|
||||
const openForm = (page: Page) => signInAt(page, routePath(feature.create), word("order.form.title"));
|
||||
const openForm = (page: Page) => signInAt(page, routePath(feature.create), word(generatedMessageKey("form.title")));
|
||||
const nameField = (page: Page) =>
|
||||
page.getByRole("textbox", { name: new RegExp(word("order.form.name"), "u") });
|
||||
const saveButton = (page: Page) => page.getByRole("button", { name: word("order.form.save") });
|
||||
page.getByRole("textbox", { name: new RegExp(word(generatedMessageKey("form.name")), "u") });
|
||||
const saveButton = (page: Page) => page.getByRole("button", { name: word(generatedMessageKey("form.save")) });
|
||||
|
||||
async function expectNoBlockingViolations(page: Page) {
|
||||
const results = await new AxeBuilder({ page }).withTags(WCAG_TAGS).analyze();
|
||||
@@ -154,7 +163,7 @@ async function saveFromKeyboard(page: Page, firstAction: string) {
|
||||
test.describe("the route", () => {
|
||||
test("opens the protected list through the local demo sign-in", async ({ page }) => {
|
||||
await answerReads(page);
|
||||
await signInAt(page, routePath(feature.list), word("order.list.title"));
|
||||
await signInAt(page, routePath(feature.list), word(generatedMessageKey("list.title")));
|
||||
|
||||
// The closed menu drawer holds a second copy of the status (08-01).
|
||||
await expect(
|
||||
@@ -167,16 +176,16 @@ test.describe("the route", () => {
|
||||
// 08-04. Feature screens take their words from the catalog.
|
||||
test("draws its screens without Korean copy in en-US", async ({ page }) => {
|
||||
await answerReads(page);
|
||||
await signInAt(page, routePath(feature.list), word("order.list.title"));
|
||||
await signInAt(page, routePath(feature.list), word(generatedMessageKey("list.title")));
|
||||
await page.getByRole("combobox", { name: "언어" }).first().selectOption("en-US");
|
||||
|
||||
const main = page.getByRole("main");
|
||||
const english = feature.messages["en-US"];
|
||||
await expect(main.getByRole("heading", { level: 1 })).toHaveText(english["order.list.title"]!);
|
||||
await expect(main.getByRole("heading", { level: 1 })).toHaveText(english[generatedMessageKey("list.title")]!);
|
||||
await expect(main).not.toContainText(/[가-힣]/u);
|
||||
|
||||
await main.getByRole("link", { name: english["order.list.create"]! }).click();
|
||||
await expect(main.getByRole("button", { name: english["order.form.save"]! })).toBeVisible();
|
||||
await main.getByRole("link", { name: english[generatedMessageKey("list.create")]! }).click();
|
||||
await expect(main.getByRole("button", { name: english[generatedMessageKey("form.save")]! })).toBeVisible();
|
||||
await expect(main).not.toContainText(/[가-힣]/u);
|
||||
});
|
||||
});
|
||||
@@ -196,7 +205,7 @@ test.describe("the form", () => {
|
||||
await nameField(page).fill("Unsaved order");
|
||||
await page
|
||||
.getByRole("navigation", { name: KO_MESSAGES["template.breadcrumb"] })
|
||||
.getByRole("link", { name: word("order.list.title") })
|
||||
.getByRole("link", { name: word(generatedMessageKey("list.title")) })
|
||||
.click();
|
||||
|
||||
const dialog = page.getByRole("dialog", { name: KO_MESSAGES["form.unsaved.title"] });
|
||||
@@ -243,7 +252,7 @@ test.describe("the save", () => {
|
||||
route.fulfill({
|
||||
status: 429,
|
||||
headers: { "retry-after": "1" },
|
||||
json: failure("RATE_LIMITED", true),
|
||||
json: failure("RATE_LIMIT_EXCEEDED", "RATE_LIMIT", true),
|
||||
});
|
||||
|
||||
test("keeps the input and saves on retry", async ({ page }) => {
|
||||
@@ -281,7 +290,7 @@ test.describe("the save", () => {
|
||||
"x-correlation-id": "corr-save-500",
|
||||
"access-control-expose-headers": "x-correlation-id",
|
||||
},
|
||||
json: failure("INTERNAL_ERROR", false),
|
||||
json: failure("INTERNAL_ERROR", "INTERNAL", false),
|
||||
});
|
||||
|
||||
// 0929/08-04. The case a user most wants to report shows the id support
|
||||
@@ -331,7 +340,7 @@ test.describe("the save", () => {
|
||||
|
||||
await page.keyboard.press("Enter");
|
||||
|
||||
await expect(page.getByRole("heading", { level: 1 })).toHaveText(word("order.list.title"));
|
||||
await expect(page.getByRole("heading", { level: 1 })).toHaveText(word(generatedMessageKey("list.title")));
|
||||
await expect(page.getByRole("link", { name: ITEM.name })).toBeVisible();
|
||||
expect(calls).toHaveLength(1);
|
||||
});
|
||||
@@ -350,7 +359,7 @@ test.describe("accessibility", () => {
|
||||
] as const) {
|
||||
test(`@a11y list ${state} state has no blocking violations`, async ({ page }) => {
|
||||
await answerReads(page, list);
|
||||
await signInAt(page, routePath(feature.list), word("order.list.title"));
|
||||
await signInAt(page, routePath(feature.list), word(generatedMessageKey("list.title")));
|
||||
await expect(page.getByRole("main")).toContainText(visible);
|
||||
await expectNoBlockingViolations(page);
|
||||
});
|
||||
|
||||
@@ -184,25 +184,21 @@ async function preloadedWith(dist: string, page: string): Promise<string[]> {
|
||||
}
|
||||
|
||||
// 1103/11-09. Vite preloads a chunk together with the chunks it imports, so a
|
||||
// missing chunk leaves itself and the chunks preloaded with it unused: in the
|
||||
// A tab those of A's platform page (the tab is still on A while recovery
|
||||
// reads the release manifest), in the B tab those of B's context routes
|
||||
// module for the feature's list page. The fixture's preload check reports them in every
|
||||
// engine (WebKit's own three-second warning only did when its timer ran
|
||||
// before the test ended). They are the provoked failure's own effect; only
|
||||
// those chunks are allowed.
|
||||
// missing chunk leaves itself and the chunks preloaded with it unused. The
|
||||
// fixture's preload check reads only the documents open at the end
|
||||
// (tests/support/browser/preload-use.ts), and the A tab has become a B
|
||||
// document by then, so only B's: those of B's context routes module for the
|
||||
// feature's list page. The check reports them in every engine (WebKit's own
|
||||
// three-second warning only did when its timer ran before the test ended).
|
||||
// They are the provoked failure's own effect; only those chunks are allowed
|
||||
// (1112/03-06: the A list here covered nothing but a B chunk of the same name).
|
||||
test.use({
|
||||
allowedBrowserFailure: async ({ browserName: _engine }, provide) => {
|
||||
if (!builds) throw new Error("Fixture builds were not prepared.");
|
||||
const aManifest = await viteManifest(builds.dist.a);
|
||||
const bManifest = await viteManifest(builds.dist.b);
|
||||
const files = [
|
||||
...(await preloadedWith(builds.dist.a, pageSource(aManifest, PLATFORM))),
|
||||
...(await preloadedWith(
|
||||
builds.dist.b,
|
||||
routesSource(bManifest, pageSource(bManifest, FEATURE())),
|
||||
)),
|
||||
].map((file) => file.replaceAll(".", String.raw`\.`));
|
||||
const files = (
|
||||
await preloadedWith(builds.dist.b, routesSource(bManifest, pageSource(bManifest, FEATURE())))
|
||||
).map((file) => file.replaceAll(".", String.raw`\.`));
|
||||
await provide(
|
||||
new RegExp(
|
||||
[
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
import AxeBuilder from "@axe-core/playwright";
|
||||
import { expect, test } from "../support/browser/strict-browser-test.ts";
|
||||
import { WCAG_AXE_TAGS } from "../support/browser/axe-tags.ts";
|
||||
|
||||
test("persists an explicit color scheme through the storage contract", async ({
|
||||
page,
|
||||
@@ -11,7 +12,7 @@ test("persists an explicit color scheme through the storage contract", async ({
|
||||
await expect(page.locator("html")).toHaveAttribute("data-theme", "dark");
|
||||
await expect(page.locator("html")).toHaveCSS("color-scheme", "dark");
|
||||
const results = await new AxeBuilder({ page })
|
||||
.withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"])
|
||||
.withTags([...WCAG_AXE_TAGS])
|
||||
.analyze();
|
||||
expect(
|
||||
results.violations.filter((violation) =>
|
||||
|
||||
+4
-28
@@ -3,33 +3,15 @@
|
||||
"responses": {
|
||||
"index": {
|
||||
"cache-control": "no-cache",
|
||||
"content-type": "text/html; charset=utf-8",
|
||||
"content-security-policy": "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; form-action 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self' https:; font-src 'self'; upgrade-insecure-requests",
|
||||
"strict-transport-security": "max-age=31536000; includeSubDomains",
|
||||
"x-frame-options": "DENY",
|
||||
"referrer-policy": "strict-origin-when-cross-origin",
|
||||
"x-content-type-options": "nosniff",
|
||||
"permissions-policy": "camera=(), microphone=(), geolocation=()"
|
||||
"content-type": "text/html; charset=utf-8"
|
||||
},
|
||||
"runtimeConfig": {
|
||||
"cache-control": "no-store",
|
||||
"content-type": "application/json; charset=utf-8",
|
||||
"content-security-policy": "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; form-action 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self' https:; font-src 'self'; upgrade-insecure-requests",
|
||||
"strict-transport-security": "max-age=31536000; includeSubDomains",
|
||||
"x-frame-options": "DENY",
|
||||
"referrer-policy": "strict-origin-when-cross-origin",
|
||||
"x-content-type-options": "nosniff",
|
||||
"permissions-policy": "camera=(), microphone=(), geolocation=()"
|
||||
"content-type": "application/json; charset=utf-8"
|
||||
},
|
||||
"releaseManifest": {
|
||||
"cache-control": "no-store",
|
||||
"content-type": "application/json; charset=utf-8",
|
||||
"content-security-policy": "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; form-action 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self' https:; font-src 'self'; upgrade-insecure-requests",
|
||||
"strict-transport-security": "max-age=31536000; includeSubDomains",
|
||||
"x-frame-options": "DENY",
|
||||
"referrer-policy": "strict-origin-when-cross-origin",
|
||||
"x-content-type-options": "nosniff",
|
||||
"permissions-policy": "camera=(), microphone=(), geolocation=()"
|
||||
"content-type": "application/json; charset=utf-8"
|
||||
},
|
||||
"hashedAsset": {
|
||||
"cache-control": "public, max-age=31536000, immutable",
|
||||
@@ -38,13 +20,7 @@
|
||||
},
|
||||
"appRoute": {
|
||||
"cache-control": "no-cache",
|
||||
"content-type": "text/html; charset=utf-8",
|
||||
"content-security-policy": "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; form-action 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self' https:; font-src 'self'; upgrade-insecure-requests",
|
||||
"strict-transport-security": "max-age=31536000; includeSubDomains",
|
||||
"x-frame-options": "DENY",
|
||||
"referrer-policy": "strict-origin-when-cross-origin",
|
||||
"x-content-type-options": "nosniff",
|
||||
"permissions-policy": "camera=(), microphone=(), geolocation=()"
|
||||
"content-type": "text/html; charset=utf-8"
|
||||
},
|
||||
"serviceWorker": {
|
||||
"cache-control": "no-cache",
|
||||
|
||||
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"headers": {
|
||||
"content-security-policy": "default-src 'self'; script-src 'self' 'Unsafe-Inline'; script-src 'self'; object-src 'none'"
|
||||
}
|
||||
}
|
||||
@@ -2,6 +2,10 @@
|
||||
* Timeouts for Vitest tests that start a child process
|
||||
* (docs/work/reference/testing.md 2절: such a test declares its own timeout).
|
||||
* tests/setup.ts fails a test on the default timeout that starts one.
|
||||
* It is also the one way to give any test, describe or hook more than the
|
||||
* default, a long in-process run included, so every such number at a call is
|
||||
* a desktop measurement. tests/unit/test-timeout-declarations.test.ts refuses
|
||||
* a number written by hand (1112/03-08).
|
||||
*/
|
||||
|
||||
/** `testTimeout` in vitest.config.ts, sized for tests that run in process. */
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user