diff --git a/.claude/rules/gates-and-budgets.md b/.claude/rules/gates-and-budgets.md index 0e2d6018..3873e9e1 100644 --- a/.claude/rules/gates-and-budgets.md +++ b/.claude/rules/gates-and-budgets.md @@ -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)은 알리지 않는다. 알림은 막지 않는다. 의도한 변경이면 커밋 본문에 이유와 결정 출처를 적는다. diff --git a/.claude/rules/tests.md b/.claude/rules/tests.md index 70cea1e7..9fcb515b 100644 --- a/.claude/rules/tests.md +++ b/.claude/rules/tests.md @@ -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()`로만 준다(손 숫자는 `tests/unit/test-timeout-declarations.test.ts`가 거절). ## 돌리는 법 -- 노트북에서는 돌리지 않는다. 한 파일도 desktop에서: `scripts/verify.sh script test:unit`, 또는 `ssh desktop`으로 `node scripts/run-vitest.ts run `(이 runner가 생성물을 먼저 만든다. `pnpm exec vitest run `은 import 오류로 실패한다). +- 노트북에서는 돌리지 않는다. 한 파일도 desktop에서 `scripts/verify.sh exec -- node scripts/run-vitest.ts run `로 돌린다(이 runner가 생성물을 먼저 만든다. `pnpm exec vitest run `은 import 오류로 실패한다). 실행 위치의 정본은 `docs/work/operate.md` 4.1절이다. diff --git a/.claude/skills/fe-a11y/SKILL.md b/.claude/skills/fe-a11y/SKILL.md index eb80cea5..d3b2def6 100644 --- a/.claude/skills/fe-a11y/SKILL.md +++ b/.claude/skills/fe-a11y/SKILL.md @@ -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절 diff --git a/.gitea/workflows/quality-gates.yml b/.gitea/workflows/quality-gates.yml index 57025662..44f3c4d3 100644 --- a/.gitea/workflows/quality-gates.yml +++ b/.gitea/workflows/quality-gates.yml @@ -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: diff --git a/AGENTS.md b/AGENTS.md index 8fe3f183..3bb1c0fd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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`. ## 일하는 방식 diff --git a/CLAUDE.md b/CLAUDE.md index 89674dd6..54d85926 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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절, 말투와 길이는 소유자 전역 설정을 따른다. diff --git a/README.md b/README.md index c79142ab..9a3c24b7 100644 --- a/README.md +++ b/README.md @@ -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//` 아래로 간다. 시험 서버는 늘 빈 포트를 고른다. 변수 목록은 설계서 `docs/design/2026-07-26-frontend-platform-testing-strategy-design.md` 13.6절에 있다. +- 한 checkout에서는 게이트를 하나씩 돌린다. 게이트와 증거 검사가 고정된 `dist/`·`artifacts/` 경로를 읽는다. Playwright 실행 둘은 각자 `TEST_RUN_ID`를 주면 한 checkout을 같이 쓸 수 있다. 그 빌드·결과·보고서는 `.tmp/runs//` 아래로 간다. 시험 서버는 늘 빈 포트를 고른다. 변수 목록의 정본은 `scripts/lib/run-isolation.ts`(`TEST_RUN_ID_VARIABLE`, `TEST_PORT_VARIABLES`)다. 외부 증거가 필요한 게이트: @@ -274,11 +274,12 @@ git merge --no-ff template/ # shared history git merge-recursive -- HEAD template/ # 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 ^ -- `. -- 받은 뒤 「검증」 절의 로컬 merge 게이트를 돌리고, **[계약]** 행이 말하는 백엔드·배포 변경을 하고, 태그까지 따라잡았으면 `.template-origin`을 고친다. 받은 수정은 `git revert`로 되돌린다. +- 받은 뒤 「검증」 절의 로컬 merge 게이트를 돌리고, **[계약]** 행이 말하는 백엔드·배포 변경을 하고, 위 기준점을 받은 범위의 끝으로 옮긴다. 받은 수정은 `git revert`로 되돌린다. -결함: 바꾸지 않은 `.template-origin` 커밋 checkout에서 재현되면 템플릿 결함이다. 그 커밋과 재현 방법을 템플릿 repo에 알린다. 템플릿 관리자가 분류하고 CHANGELOG 항목과 함께 수정을 낸다. 프로젝트의 변경이 있어야 재현되는 문제는 프로젝트의 몫이고, 템플릿 수정을 자기 사본에 적용하는 것도 프로젝트의 일이다. +결함: 바꾸지 않은 `.template-origin` 커밋 checkout에서 재현되면 템플릿 결함이다. 템플릿이 주는 선택 기능(opt-in recipe·adapter, `create:feature`가 만든 기능)을 문서대로 켜거나 더한 것만 다르고 재현되는 것도 템플릿 결함이다. 그 커밋, 켠 선택 기능, 재현 방법을 템플릿 repo에 알린다. 템플릿 관리자가 분류하고 CHANGELOG 항목과 함께 수정을 낸다. 프로젝트의 변경이 있어야 재현되는 문제는 프로젝트의 몫이고, 템플릿 수정을 자기 사본에 적용하는 것도 프로젝트의 일이다. ## 규칙과 기여 diff --git a/config/ci/gates.json b/config/ci/gates.json index 233bc9d9..fa629cb4 100644 --- a/config/ci/gates.json +++ b/config/ci/gates.json @@ -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" ] }, { diff --git a/config/repository-layout.json b/config/repository-layout.json index 5f0f8b35..38523efa 100644 --- a/config/repository-layout.json +++ b/config/repository-layout.json @@ -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)", diff --git a/config/scale/feature-shape-ceilings.json b/config/scale/feature-shape-ceilings.json index 18a3f356..2be41026 100644 --- a/config/scale/feature-shape-ceilings.json +++ b/config/scale/feature-shape-ceilings.json @@ -41,8 +41,8 @@ "initialJavascript": { "gzipBytes": 194354, "files": 17, - "firstFeatureGzipBytes": 6327, - "perFeatureGzipBytes": 539, - "perContextGzipBytes": 4 + "firstFeatureGzipBytes": 6355, + "perFeatureGzipBytes": 528, + "perContextGzipBytes": 21 } } diff --git a/docs/accessibility/manual-checklist.md b/docs/accessibility/manual-checklist.md index 85f320e3..cb83f5b9 100644 --- a/docs/accessibility/manual-checklist.md +++ b/docs/accessibility/manual-checklist.md @@ -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: - 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 발견이 없었다. diff --git a/docs/accessibility/route-reviews/APP_HOME.md b/docs/accessibility/route-reviews/APP_HOME.md index 12a847a9..033989c1 100644 --- a/docs/accessibility/route-reviews/APP_HOME.md +++ b/docs/accessibility/route-reviews/APP_HOME.md @@ -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 diff --git a/docs/accessibility/route-reviews/EXAMPLES_PLATFORM.md b/docs/accessibility/route-reviews/EXAMPLES_PLATFORM.md index d6280cbe..28d9d6d0 100644 --- a/docs/accessibility/route-reviews/EXAMPLES_PLATFORM.md +++ b/docs/accessibility/route-reviews/EXAMPLES_PLATFORM.md @@ -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 diff --git a/docs/accessibility/route-reviews/NOT_FOUND.md b/docs/accessibility/route-reviews/NOT_FOUND.md index f69a7836..729ae595 100644 --- a/docs/accessibility/route-reviews/NOT_FOUND.md +++ b/docs/accessibility/route-reviews/NOT_FOUND.md @@ -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 diff --git a/docs/architecture/backend-api-and-server-state-contract.md b/docs/architecture/backend-api-and-server-state-contract.md index 86dd5aeb..2f1e2083 100644 --- a/docs/architecture/backend-api-and-server-state-contract.md +++ b/docs/architecture/backend-api-and-server-state-contract.md @@ -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` diff --git a/docs/architecture/capability-consumer-experience.md b/docs/architecture/capability-consumer-experience.md index 1d5f65ff..88c10350 100644 --- a/docs/architecture/capability-consumer-experience.md +++ b/docs/architecture/capability-consumer-experience.md @@ -20,7 +20,7 @@ feature가 소유한 경계 코드와 application 코드는 다음 네 파일이 - `adapters/-http-gateway.ts` - `adapters/create--feature-input.ts` -이 문서는 이 파일들의 줄 수를 적어 두지 않는다. 손으로 적은 줄 수가 코드와 어긋난 적이 있다(리뷰 14-07). +이 문서는 이 파일들의 줄 수를 적어 두지 않는다. 손으로 적은 줄 수가 코드와 어긋난 적이 있다(리뷰 0925/14-07). 생성한 feature에서 이 네 파일에 `wc -l`을 돌려 잰다. 중요한 경계 지표는 단순 합계가 아니다. 이 파일들이 플랫폼에 대해 무엇을 알아야 하는지다. diff --git a/docs/architecture/layers.md b/docs/architecture/layers.md index 6a1e3778..f93d60ca 100644 --- a/docs/architecture/layers.md +++ b/docs/architecture/layers.md @@ -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, 파싱 실패, diff --git a/docs/architecture/optional-adapter-recipes.md b/docs/architecture/optional-adapter-recipes.md index 98803fbd..19e66d3b 100644 --- a/docs/architecture/optional-adapter-recipes.md +++ b/docs/architecture/optional-adapter-recipes.md @@ -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://`을 더한다. `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 투영, 재전송 없음 +짝 백엔드 스트리밍 → 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` diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md index a0de081b..5bbed5a5 100644 --- a/docs/architecture/starter-experience.md +++ b/docs/architecture/starter-experience.md @@ -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)다. ### 스타터 화면 바꾸기 diff --git a/docs/architecture/static-delivery.md b/docs/architecture/static-delivery.md index 74ed06e8..9431c129 100644 --- a/docs/architecture/static-delivery.md +++ b/docs/architecture/static-delivery.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 묶음이 서로 diff --git a/docs/design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md b/docs/design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md index 40f7401a..6ed3ba21 100644 --- a/docs/design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md +++ b/docs/design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md @@ -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 diff --git a/docs/ledger/estimates.jsonl b/docs/ledger/estimates.jsonl index 1e02d610..04c882b5 100644 --- a/docs/ledger/estimates.jsonl +++ b/docs/ledger/estimates.jsonl @@ -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분 뒤에 적었다(인계 대기 중 시작)"} diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index d298aeb7..a49d0e6b 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -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/.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/-routes.ts`: 링크용 URL 함수. route ID를 받아 `buildRouteUrl`(`src/presentation/routes/route-codecs.ts`)로 경로를 채운다. - 문구 `route..title`, `route..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/.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//` 아래에 생긴다. - 서버 포트는 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). diff --git a/docs/manual/02-decision-tables.md b/docs/manual/02-decision-tables.md index 145996e6..56da9ac5 100644 --- a/docs/manual/02-decision-tables.md +++ b/docs/manual/02-decision-tables.md @@ -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/`). **틀리면** diff --git a/docs/manual/03-outside-feature-folder.md b/docs/manual/03-outside-feature-folder.md index c1f82f7d..16e92bd7 100644 --- a/docs/manual/03-outside-feature-folder.md +++ b/docs/manual/03-outside-feature-folder.md @@ -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: