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/desktop-gates/SKILL.md b/.claude/skills/desktop-gates/SKILL.md index f2f74502..cbcc76da 100644 --- a/.claude/skills/desktop-gates/SKILL.md +++ b/.claude/skills/desktop-gates/SKILL.md @@ -19,6 +19,6 @@ description: 이 프론트 repo에서 pnpm·게이트·테스트·빌드·브라 - 먼저 무엇을 돌릴지만 보려면 `--dry-run`. 4. 스크립트가 하는 일: 지금 트리를 패치로 보내고, desktop 공유 checkout에서 새 worktree를 만들어 같은 트리인지 해시로 보고, 깨끗한 커밋 하나로 만들어 오프라인 설치 뒤 `flock /tmp/claude-gates/heavy.lock` 아래 CI env(`CI=true` 등)로 돌린다. 공유 checkout의 브랜치와 stash는 건드리지 않는다. push하지 않는다. 5. 결과를 읽는다: desktop `/tmp/claude-gates/<작업 이름>/summary.txt`(첫 줄이 트리 해시), 게이트별 로그, `gate-artifacts/`, `status-after.txt`(비어 있어야 한다). -6. FE-GATE-013은 desktop에서 호스트 제약(user namespace)으로 실패한다. `parts`로 뒤 명령 결과를 함께 적는다. 실패가 그 제약 하나뿐이고 뒤 명령이 모두 rc=0일 때만 merge 판정에서 뺀다(`docs/work/reference/gates.md` 3절). +6. FE-GATE-013은 `scripts/verify.sh`가 시스템 컨테이너(`scripts/run-in-system-container.sh`) 안에서 돌린다. 다른 게이트와 같이 rc로 적는다. 컨테이너를 띄울 수 없는 호스트에서만 `VERIFY_HOST_ENVIRONMENT=off`로 호스트에서 돌리고, 실패가 user namespace 제약 하나뿐이고 뒤 명령이 모두 rc=0일 때 merge 판정에서 뺀다(`docs/work/reference/gates.md` 3절). 7. 실패하면 기준 커밋에서도 돌려 이번 변경 몫인지 가린다. 다시 돌려 통과한 결과를 "통과"로 쓰지 않는다. 8. 보고에는 단계·게이트, rc, 시간, 핵심 숫자, 직전 부하, 트리 해시, 로그 경로를 적는다(`docs/work/operate.md` 8절 표). 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/.claude/skills/fe-structure/SKILL.md b/.claude/skills/fe-structure/SKILL.md index 77a755a4..c7ce06b0 100644 --- a/.claude/skills/fe-structure/SKILL.md +++ b/.claude/skills/fe-structure/SKILL.md @@ -39,7 +39,7 @@ paths: 7. 같은 사실(스키마 메타, 레지스트리 행, 허용 키, 빌드 입력 목록, 저장 키)을 원본과 따로 손으로 적는다. 원본에서 뽑거나 대조 시험을 같이 둔다. — `docs/work/reference/structure.md` 8절, 결함 패턴 S1 8. 제품마다 다른 것을 템플릿 소유 파일에 넣는다. 동기화마다 같은 파일이 충돌한다. 제품 소유 자리(`src/bootstrap/product-composition.ts`, `src/contracts/product-contracts.ts`, `config/ci/product-gates.json`)에 둔다. — `docs/work/reference/structure.md` 10절, 결함 패턴 S4 9. adapter 파일을 더하거나 옮기고 `docs/reviews/adapters/INVENTORY.md`를 같은 커밋에서 고치지 않는다(`check:adapter-inventory` 실패). 최상위 `src/` 폴더를 바꾸고 `docs/architecture/layers.md` 표와 세 문서의 같은 문장을 고치지 않는다(`verify:documentation` 실패). — `docs/work/reference/structure.md` 3절 -10. 지우거나 옮긴 코드가 지키던 시험·검사를 같이 잃는다. 지우기 전에 그 코드를 읽는 시험·검사를 `git grep`으로 찾는다. 지울 수 있다고 한 단위는 지워도 FE-GATE-020이 통과해야 한다. — `docs/work/reference/structure.md` 9·12절, 결함 패턴 T10·G11 +10. 지우거나 옮긴 코드가 지키던 시험·검사를 같이 잃는다. 지우기 전에 그 코드를 읽는 시험·검사를 `git grep`으로 찾는다. 지울 수 있다고 한 단위는 지워도 FE-GATE-020(기능)과 FE-GATE-030(선택 runtime, main 단계)이 통과해야 한다. — `docs/work/reference/structure.md` 9·12절, 결함 패턴 T10·G11 11. 공개 포트·배럴 표면의 시그니처를 바꾼다. 추가만 하고, 깨야 하면 결정 표에 적고 BREAKING으로 커밋한다. 이름은 새 이름을 내고 옛 이름을 한 릴리스 동안 `@deprecated` 별칭으로 남긴다. — `docs/work/reference/structure.md` 9절 12. `src/bootstrap`에 업무 규칙이나 페이지 흐름을 둔다. 판정·정책은 `src/application`·`src/platform`·기능 폴더다. — `src/bootstrap/AGENTS.md` @@ -62,7 +62,7 @@ pnpm은 desktop에서만 돈다(`docs/work/operate.md` 4.1절). 노트북에서 - 경계 전체: `scripts/verify.sh gate FE-GATE-010`(`check:architecture`, `check:adapter-inventory`, `check:registries`, `check:request-fanout`, `check:app-build-input`, `check:browser-file-storage-boundaries`, `check:realtime-boundaries`) - 규칙을 고쳤으면 `check:architecture`가 함께 돌리는 그래프 fixture(`tests/fixtures/architecture/dependency-graph/barrel` 등)가 거절과 허용을 둘 다 고정하는지 본다. 규칙을 꺼 본 사본에서 그 fixture 검사가 실패해야 한다. ESLint 계층 패턴은 `tests/unit/architecture-lint-fixtures.test.ts`(FE-GATE-005)가 같은 일을 한다. -- 지울 수 있는 단위·구조를 바꿨으면: `scripts/verify.sh gate FE-GATE-020`(14~21분, 드릴 복사 목록은 `scripts/lib/removal-fixture.ts`) +- 지울 수 있는 단위·구조를 바꿨으면: `scripts/verify.sh gate FE-GATE-020 FE-GATE-030`(합쳐 약 11분, 드릴 복사 목록은 `scripts/lib/removal-fixture.ts`). FE-GATE-030은 PR에서 돌지 않는다 - 최상위 폴더·문서 문장: `scripts/verify.sh script verify:documentation` - 편집 직후 훅(N3)은 의심 import를 알리기만 한다. 그래프 전체(사이클)는 `check:architecture`만 본다. diff --git a/.claude/skills/fe-testing/SKILL.md b/.claude/skills/fe-testing/SKILL.md index b46bb488..e53977c7 100644 --- a/.claude/skills/fe-testing/SKILL.md +++ b/.claude/skills/fe-testing/SKILL.md @@ -57,7 +57,7 @@ pnpm·브라우저는 desktop에서만 돈다(`docs/work/operate.md` 4.1절). - 작업 중: `scripts/verify.sh exec -- node scripts/run-vitest.ts run <파일>`, 브라우저 spec 하나는 `scripts/verify.sh exec -- corepack pnpm exec playwright test ` - 층별 게이트: FE-GATE-004(runtime-schema), FE-GATE-005(unit·contract·coverage·scale pr), FE-GATE-006(component), FE-GATE-007(integration·HTTP 시나리오 증거·recipes), FE-GATE-008(e2e·browser-capabilities·storybook·visual·시험 증거), FE-GATE-009(a11y). 예: `scripts/verify.sh gate FE-GATE-006` -- FE-GATE-013(system)은 desktop에서 호스트 제약(user namespace)으로 실패한다. `scripts/verify.sh parts FE-GATE-013`으로 뒤 명령까지 돌리고 `docs/work/reference/gates.md` 3절 문구로 적는다. +- FE-GATE-013(system)은 `scripts/verify.sh`가 시스템 컨테이너(`scripts/run-in-system-container.sh`) 안에서 돌린다. 컨테이너를 띄울 수 없는 호스트에서만 `docs/work/reference/gates.md` 3절 조건과 문구로 적는다. - 시험 기반 자체(음성 fixture가 정해진 오류로 실패해야 통과, `check:ci:gating`): `scripts/verify.sh gate FE-GATE-029` - 커밋 전 묶음은 `docs/work/reference/gates.md` 2절 표, merge 가능 판정은 `scripts/verify.sh merge`. - 흔들림을 고친 뒤 같은 조건 반복 실행(예: 30회)으로 실패 0과 횟수를 적는다. — `docs/work/reference/testing.md` 5절 diff --git a/.gitea/workflows/quality-gates.yml b/.gitea/workflows/quality-gates.yml index a2b9c247..44f3c4d3 100644 --- a/.gitea/workflows/quality-gates.yml +++ b/.gitea/workflows/quality-gates.yml @@ -24,6 +24,10 @@ on: permissions: contents: read +concurrency: + group: frontend-quality-gates-${{ gitea.event_name }}-${{ gitea.ref }}-${{ inputs.stage }} + cancel-in-progress: ${{ gitea.event_name != 'workflow_dispatch' }} + env: CI: "true" VITE_BUILD_ID: "gitea-${{ gitea.run_id }}-${{ gitea.run_attempt }}" @@ -78,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: @@ -106,7 +110,7 @@ jobs: run: corepack pnpm ci:gate -- FE-GATE-007 - name: "FE-GATE-013 / security" if: ${{ !cancelled() }} - run: corepack pnpm ci:gate -- FE-GATE-013 + run: scripts/run-in-system-container.sh corepack pnpm ci:gate -- FE-GATE-013 - name: "FE-GATE-020 / removability" if: ${{ !cancelled() }} run: corepack pnpm ci:gate -- FE-GATE-020 @@ -123,6 +127,10 @@ jobs: if: ${{ gitea.event_name != 'workflow_dispatch' || (inputs.stage != 'documentation' && inputs.stage != 'main') }} runs-on: ubuntu-latest timeout-minutes: 45 + container: + image: "mcr.microsoft.com/playwright:v1.62.0-noble@sha256:baed2032d533817f3dbe6425de795788430ba345e819a1201337009ba17c9d07" + env: + CI_RUNNER_IMAGE: "mcr.microsoft.com/playwright:v1.62.0-noble@sha256:baed2032d533817f3dbe6425de795788430ba345e819a1201337009ba17c9d07" steps: - uses: https://github.com/actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 with: @@ -134,9 +142,9 @@ jobs: run: | corepack enable corepack pnpm install --frozen-lockfile --ignore-scripts - - name: Install Playwright browsers + - name: Install visual-test fonts run: | - corepack pnpm exec playwright install --with-deps chromium firefox webkit + $(command -v sudo || true) apt-get update $(command -v sudo || true) apt-get install -y fonts-noto-core fonts-noto-cjk fonts-noto-cjk-extra fonts-liberation - name: "FE-GATE-008 / e2e" if: ${{ !cancelled() }} @@ -295,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: @@ -341,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: @@ -574,7 +586,7 @@ jobs: if-no-files-found: error main_gate: - name: "main / checker self-tests" + name: "main / self-tests and removal drills" if: ${{ (gitea.event_name == 'push' && startsWith(gitea.ref, 'refs/heads/')) || (gitea.event_name == 'workflow_dispatch' && inputs.stage == 'main') }} runs-on: ubuntu-latest timeout-minutes: 45 @@ -592,6 +604,9 @@ jobs: - name: "FE-GATE-029 / checker-self-tests" if: ${{ !cancelled() }} run: corepack pnpm ci:gate -- FE-GATE-029 + - name: "FE-GATE-030 / optional-removability" + if: ${{ !cancelled() }} + run: corepack pnpm ci:gate -- FE-GATE-030 - name: Upload main gate evidence if: always() uses: https://github.com/ChristopherHX/gitea-upload-artifact@81f940d004763f986ba3582c007fd842dd5cb0d7 diff --git a/AGENTS.md b/AGENTS.md index 37898d01..3bb1c0fd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,8 +25,8 @@ ## 검증 - 진입점은 `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`로 돌려 통과한 것이다. 골라 돌린 결과로 말하지 않는다. desktop의 FE-GATE-013은 `docs/work/reference/gates.md` 3절 문구로 적는다. -- 문서·지침을 고쳤으면 `scripts/verify.sh docs`(노트북). +- "merge 가능"은 merge 단계 게이트 전부를 `CI=true`로 돌려 통과한 것이다. 골라 돌린 결과로 말하지 않는다. FE-GATE-013은 `scripts/run-in-system-container.sh` 안에서 돈다(`docs/work/reference/gates.md` 3절). +- 문서·지침을 고쳤으면 `scripts/verify.sh docs`(노트북)와 desktop `scripts/verify.sh script verify:documentation`. ## 일하는 방식 diff --git a/CHANGELOG.md b/CHANGELOG.md index 19965034..3e351cce 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,43 @@ - 괄호 안 ID는 리뷰 발견 ID다. `MMDD/NN-MM`으로 적는다. `MMDD`는 리뷰 폴더 `docs/reviews/YYYY-MM-DD-maturity-review/`의 월일이고, 근거와 재현 조건은 그 폴더의 영역 문서에 있다. 복사한 프로젝트가 README대로 `docs/reviews/`를 지웠다면 이 폴더와 `PRODUCT.md`는 원본 템플릿 repo에서 찾는다. 라운드마다 `NN-MM`을 새로 매기므로 같은 `14-02`라도 라운드가 다르면 다른 결함이다. `F-N`은 그 라운드 `FOLLOW-UP.md`의 ID다. 리뷰 README의 절은 `MMDD README N.N`으로 적고 다시 돌린 항목은 그 뒤에 `X2`처럼 번호를 붙인다. 영역 문서가 따로 매긴 ID는 `MMDD NN 영역 P-NN-NN`, 짝 백엔드 리뷰의 ID는 `백엔드 리뷰 MMDD/NN-MM`으로 적는다. `tests/unit/changelog-review-ids.test.ts`가 라운드 없는 ID와 이 꼴을 벗어난 참조를 막는다. - 0.2.0의 커밋 해시는 브랜치 `fix/maturity-review-2026-09-25`에서 만들었고, `main`에서도 같은 해시로 찾을 수 있다(2026-11-03에 52개 모두 확인). 그 뒤 절은 절 머리에 범위(기준 커밋과 브랜치)를 적고, 그 절의 해시는 모두 그 범위에 있다. 통합에서 해시를 다시 쓴 뒤(fixup 접기, rebase)에는 절의 해시와 범위 커밋 본문의 해시를 `git merge-base --is-ancestor <해시> <브랜치 끝>`으로 하나씩 대조하고, 결과를 그 라운드 리뷰 README의 조치 절에 적는다. 1105 통합은 이 대조를 하지 않아, 올린 커밋 `287dc6f`의 본문이 다시 짓기 전 해시 둘을 가리킨다. 맞는 해시는 그 라운드 리뷰 README의 D7 행에 있다 (1106/14-02, 1105 README 16.2). 0.2.0의 커밋 제목은 라운드 없이 ID만 적었다(`git log --grep '03-03'`). +## 미출시 — `db6a6eb6` → CI를 runner에서 초록으로, merge 시간 줄이기 + +Gitea runner에서 merge 단계를 초록으로 만들고, worker를 늘리지 않고 같은 시험을 두 번 도는 곳과 job마다 같은 것을 내려받는 곳을 없앤다. 제품 코드는 바뀌지 않는다. + +### 먼저 할 일 + +- FE-GATE-013은 `scripts/run-in-system-container.sh`가 띄우는 privileged systemd 컨테이너 안에서 돈다. 자기 runner가 job에서 Docker로 privileged 컨테이너를 띄울 수 없으면 이 게이트가 실패한다. 그런 runner면 `docs/operations/ci-quality-gates.md` FE-GATE-013 절의 호스트 조건을 갖춘 runner에서 돌린다. +- merge / browser tests job이 Playwright 공식 이미지(`config/ci/gates.json`의 `browser-install.image`, digest 고정)에서 돈다. `@playwright/test`를 올릴 때 이 digest도 같은 버전으로 바꾼다(`tests/unit/ci-browser-image.test.ts`가 막는다). +- devDependencies에서 `dependency-cruiser`가 빠진다. 그 CLI를 따로 쓰고 있었으면 다시 더한다. +- 선택 runtime 제거 드릴 셋이 merge의 FE-GATE-020에서 main 단계의 새 게이트 FE-GATE-030으로 옮는다. main job 이름이 `main / self-tests and removal drills`로 바뀐다. 그 이름을 필수 검사로 걸었으면 바꾼다. 선택 runtime을 바꾸는 PR은 `scripts/verify.sh gate FE-GATE-030`을 직접 돌린다. + +### 보안·계약 변경 + +| 표시 | 변경 | 영향 경로 | 커밋 | +| --- | --- | --- | --- | +| [계약] | 게이트 필드 `hostEnvironment`(`"system-container"`)를 더한다. 생성기와 `scripts/verify.sh`가 그 게이트를 `scripts/run-in-system-container.sh`로 감싸고, 실행 검사는 계약이 정한 접두어로 돈 줄만 센다. FE-GATE-013에 준다 | `config/ci/gates.json`, `scripts/contracts/ci-gates.ts`, `scripts/generate-ci-workflow.ts`, `scripts/verify.sh`, `scripts/run-in-system-container.sh`, `config/ci/system-container.Dockerfile` | `1d3eb901` | +| [계약] | 게이트 FE-GATE-030 `optional-removability`(main 단계)를 더하고 FE-GATE-020에서 선택 runtime 제거 드릴 셋을 옮긴다. 정규 게이트 ID는 001..030, MAIN_READY는 029·030, 계약 보고서 `gateCount`는 29다(소유자 결정 2026-11-12) | `config/ci/gates.json`, `scripts/contracts/ci-gates.ts`, `scripts/lib/promotion-readiness.ts`, `scripts/lib/ci-contract-report.ts`, `scripts/lib/feature-scaffold-drill.ts` | `8de1403b` | +| [계약] | `browser-install` 단계에 `image`(Playwright 레지스트리 noble 태그 + digest)를 더한다. 생성기는 그 job의 container와 job env `CI_RUNNER_IMAGE`로 그리고, 단계는 글꼴만 설치한다. gate-sequence job에만 둔다 | 같은 파일, `tests/unit/ci-browser-image.test.ts` | `92abfd20` | + +### 그 밖의 변경 + +| 변경 | 영향 경로 | 커밋 | +| --- | --- | --- | +| `fixture-node-modules` 시험이 「CI 아님」 설치를 `CI=false`로 흉내 낸다. runner의 벤더 변수(`GITEA_ACTIONS` 등) 때문에 FE-GATE-005·020이 runner에서만 실패했다 | `tests/unit/fixture-node-modules.test.ts` | `ddfcb6f6` | +| `scripts/verify.sh parts`가 게이트 명령의 `args`를 넘긴다 | `scripts/verify.sh`, `scripts/tests/test_verify.py` | `79a225b6` | +| `check:browser-file-storage-boundaries`가 fixture마다 eslint를 띄우지 않고 ESLint API 한 번으로 같은 판정을 한다 | `scripts/check-browser-file-storage-boundaries.ts` | `0d8e4f5a` | +| FE-GATE-020 드릴이 한 복사본에서 같은 시험 파일을 두 번 돌지 않는다: scaffold 드릴은 `test:coverage`가 도는 plain suite를 빼고, feature-removal은 `test:all` 대신 `test:coverage` 밖에 남는 suite만 더 돈다 | `scripts/lib/feature-scaffold-drill.ts`, `scripts/test-sample-removal.ts`, `tests/unit/removal-drill-test-paths.test.ts` | `b4210753` | +| 쓰지 않는 `dependency-cruiser`를 지우고 의존성 기준선을 다시 승인한다 | `package.json`, `pnpm-lock.yaml`, `config/security/dependency-baseline*.json` | `66138440` | +| vitest setup이 DOM이 있는 시험 파일에만 Testing Library를 불러온다 | `tests/setup.ts` | `1f09c1cc` | +| 같은 PR·브랜치에 새 push가 오면 workflow `concurrency`가 앞 run을 취소한다. 수동 실행은 ref·stage마다 group이 따로이고 돌고 있는 run을 취소하지 않는다 | `scripts/generate-ci-workflow.ts`, `.gitea/workflows/quality-gates.yml` | `2f5eb2b4` | +| coverage include·exclude를 저장소 루트로 시작하는 패턴으로 바꾼다. vitest가 패턴을 절대 경로 어디에서나 맞춰, 이름이 `src`로 끝나는 폴더에 둔 checkout에서 루트 파일이 coverage에 들어가 risk-coverage가 실패했다 | `vitest.config.ts`, `scripts/lib/coverage-scope.ts`, `scripts/lib/v8-coverage-counter-semantics.ts` | `543518ad` | +| 위험 커버리지 모듈 목록이 `@babel/core`로 파싱하고 기본 fs를 동기로 쓴다. 판정과 검사 순서는 같다 | `scripts/lib/risk-coverage.ts` | `0bb1f0af` | +| `generateArtifactSchemas`가 writer를 받는다. 스키마 생성 시험은 fsync 없는 writer로 임시 폴더에 쓴다 | `scripts/generate-artifact-schemas.ts`, `tests/unit/json-schema.test.ts` | `198e9856` | +| HTTP 실행기의 deadline 분류 시험이 가짜 시계로 대기 지점에서 deadline을 낸다. 실제 30ms deadline이 부하에서 backoff 전에 지나 TIMEOUT 대신 전송 실패로 끝났다 | `tests/unit/http-execution-v3.test.ts` | `37a85004` | +| 위험 커버리지가 `"use strict"` 밖의 지시문(`"use client"` 등)을 문장으로 센다. V8 coverage가 그렇게 센다(`check:v8-coverage-counter-semantics` fixture에 지시문 모듈 둘) | `scripts/lib/risk-coverage.ts`, `scripts/lib/v8-coverage-counter-semantics.ts` | `0c3c9d33` | +| e2e fixture build를 브라우저 project마다가 아니라 run에 한 번 만든다. global setup이 공유 폴더를 만들고 처음 닿은 worker만 build한다. 자기 spec에서 `prepareServiceWorkerBuilds`를 부르면 `key`를 준다 | `playwright.config.ts`, `tests/e2e/support/shared-fixture-builds.ts`, `tests/e2e/support/fixture-builds.ts`, `tests/e2e/support/service-worker-builds.ts` | `c6d7f43a` | + ## 미출시 — `8327e221` → 하네스와 작업 매뉴얼 2026-11-07 소유자가 정한 Claude Code 작업 환경(하네스)을 백엔드 템플릿과 같은 방식으로 둔다(design-docs `harness/01-harness-design.md` 13절). 루트 지침 `AGENTS.md`(정본)와 `CLAUDE.md`(가져오기), `.claude/`(규칙·스킬·서브에이전트·권한·훅), 작업 매뉴얼 `docs/work/`, 검증 진입점 `scripts/verify.sh`, 장부 `docs/ledger/`다. 제품 코드와 게이트 동작은 바뀌지 않는다. 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 28124130..9a3c24b7 100644 --- a/README.md +++ b/README.md @@ -207,7 +207,7 @@ done ``` - FE-GATE-008과 FE-GATE-009는 Playwright 브라우저가 필요하다. FE-GATE-012는 먼저 앱을 빌드한다. -- FE-GATE-013은 bubblewrap이 비특권 user·network namespace를 만들 수 있는 Linux 호스트가 필요하다. Ubuntu 23.10 이후는 기본으로 거절한다. 첫 단계가 그렇게 알려 주고, 고치는 법은 `docs/operations/ci-quality-gates.md`에 있다. +- FE-GATE-013은 systemd와 bubblewrap이 있는 호스트가 필요해 `scripts/run-in-system-container.sh`가 띄우는 privileged systemd 컨테이너 안에서 돈다. Docker가 그런 컨테이너를 띄울 수 있어야 한다. 위 반복문에서는 `scripts/run-in-system-container.sh corepack pnpm ci:gate -- FE-GATE-013`으로 돌린다. 자세한 조건은 `docs/operations/ci-quality-gates.md`에 있다. - `config/ci/product-gates.json`에 적은 제품 검사(`PRODUCT-GATE-NNN`)는 workflow의 `product_merge_gate` job에서 돌고, release 단계가 그 job을 기다린다. workflow처럼 돌리려면 workflow의 환경을 먼저 준다. `CI=true`이면 실행기와 release 빌드가 CI 빌드 식별값을 요구한다. 테스트가 사본으로 만드는 빌드(fixture 빌드, 시각 골든 빌드, 브라우저 시험의 dev 서버)는 이 값과 상관없이 로컬 빌드로 돈다(`scripts/lib/build-environment.ts`의 `localBuildEnvironment`). 깨끗한 clone에서 돌린다. `ci:gate`는 게이트의 첫 실패 명령에서 멈춘다. @@ -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 1d8fe31c..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", @@ -1574,6 +1580,12 @@ "path": "artifacts/quality/gates/FE-GATE-029.txt", "schemaId": "text", "production": "runner-generated" + }, + { + "id": "artifact-artifacts-quality-gates-FE-GATE-030-txt", + "path": "artifacts/quality/gates/FE-GATE-030.txt", + "schemaId": "text", + "production": "runner-generated" } ], "gates": [ @@ -1801,8 +1813,9 @@ "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" }, { "id": "FE-GATE-014", @@ -1879,18 +1892,12 @@ "name": "removability", "commandIds": [ "test-sample-removal", - "test-feature-scaffold", - "test-optional-recipe-removal", - "test-browser-file-storage-removal", - "test-realtime-removal" + "test-feature-scaffold" ], "logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-020-txt", "evidenceArtifactIds": [ "artifact-artifacts-tests-sample-removal-xml", - "artifact-artifacts-tests-feature-scaffold-xml", - "artifact-artifacts-tests-optional-recipe-removal-xml", - "artifact-artifacts-tests-browser-file-storage-runtime-removal-xml", - "artifact-artifacts-tests-realtime-runtime-removal-xml" + "artifact-artifacts-tests-feature-scaffold-xml" ], "retentionClassId": "merge-cycle" }, @@ -1989,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" ], @@ -2031,6 +2039,22 @@ "artifact-artifacts-security-supply-chain-provider-fixtures-json" ], "retentionClassId": "merge-cycle" + }, + { + "id": "FE-GATE-030", + "name": "optional-removability", + "commandIds": [ + "test-optional-recipe-removal", + "test-browser-file-storage-removal", + "test-realtime-removal" + ], + "logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-030-txt", + "evidenceArtifactIds": [ + "artifact-artifacts-tests-optional-recipe-removal-xml", + "artifact-artifacts-tests-browser-file-storage-runtime-removal-xml", + "artifact-artifacts-tests-realtime-runtime-removal-xml" + ], + "retentionClassId": "merge-cycle" } ], "stages": [ @@ -2107,7 +2131,8 @@ "readiness": "MAIN_READY", "needs": [], "gateIds": [ - "FE-GATE-029" + "FE-GATE-029", + "FE-GATE-030" ] } ], @@ -2221,7 +2246,8 @@ "kind": "frozen-install" }, { - "kind": "browser-install" + "kind": "browser-install", + "image": "mcr.microsoft.com/playwright:v1.62.0-noble@sha256:baed2032d533817f3dbe6425de795788430ba345e819a1201337009ba17c9d07" }, { "kind": "run-gate" @@ -2487,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" ] }, { @@ -2574,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" ] }, { @@ -2858,13 +2892,14 @@ }, { "id": "main_gate", - "displayName": "main / checker self-tests", + "displayName": "main / self-tests and removal drills", "kind": "gate-sequence", "needs": [], "condition": "main", "timeoutMinutes": 45, "gateIds": [ - "FE-GATE-029" + "FE-GATE-029", + "FE-GATE-030" ], "browserGateIds": [], "environment": [], diff --git a/config/ci/system-container.Dockerfile b/config/ci/system-container.Dockerfile new file mode 100644 index 00000000..0fc092d4 --- /dev/null +++ b/config/ci/system-container.Dockerfile @@ -0,0 +1,16 @@ +# The host FE-GATE-013 runs on (scripts/run-in-system-container.sh): systemd as +# PID 1 with a lingering root user manager, cgroup v2 delegation, bubblewrap and +# the tools the provider sandbox calls (config/ci/gates.json hostRequirements). +# Node and pnpm are not installed here: the script copies in the caller's own, +# so the gate runs with the same versions as the job that called it. +FROM docker.io/library/ubuntu:24.04@sha256:fe81560990fae86dc4743202b2cb4d3df98d0bcf949173cecef15ce1127ef852 + +RUN apt-get update \ + && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \ + bubblewrap ca-certificates dbus dbus-user-session git systemd systemd-sysv tar util-linux \ + && rm -rf /var/lib/apt/lists/* \ + && mkdir -p /var/lib/systemd/linger \ + && touch /var/lib/systemd/linger/root + +STOPSIGNAL SIGRTMIN+3 +CMD ["/sbin/init"] 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/config/security/dependency-baseline.approval.json b/config/security/dependency-baseline.approval.json index 0ed6a64c..bdb84502 100644 --- a/config/security/dependency-baseline.approval.json +++ b/config/security/dependency-baseline.approval.json @@ -1,7 +1,7 @@ { "schemaVersion": 1, - "snapshotDigest": "1be535686bed2315cc986f51b991b269c359ce1dca34d47faee6d35b0d57cfd3", + "snapshotDigest": "ddb6db119f9f57236cc293189e013f03232371d2f0b90dc363fba36e92e5717d", "owner": "DongHyeonka", - "reason": "1103/13-03 dev-only advisory fixes: vite 8.1.6, vitest and coverage-v8 4.1.12, storybook 10.6.5, in-range updates of undici, brace-expansion, nanoid, source-map-js, postcss", - "approvedAt": "2026-11-04T13:27:48.076Z" + "reason": "remove the unused dev dependency dependency-cruiser (check:architecture replaced its CLI, which cannot read TypeScript 7; D-11)", + "approvedAt": "2026-11-11T14:48:22.848Z" } diff --git a/config/security/dependency-baseline.json b/config/security/dependency-baseline.json index f77c911d..090cb247 100644 --- a/config/security/dependency-baseline.json +++ b/config/security/dependency-baseline.json @@ -1,9 +1,9 @@ { "schemaVersion": 2, "packageManager": "pnpm@11.17.0", - "lockfileSha256": "3a818cf0ea62509ded18f9989e0df6704eb1258b8caa9543f9b227fe91fb6d30", - "dependencyCount": 562, - "directDependencyCount": 35, + "lockfileSha256": "fe32c358ba14ea2294d9afa8655ba311944931dea338ae99a9524e1566ff5938", + "dependencyCount": 542, + "directDependencyCount": 34, "dependencies": [ { "name": "@adobe/css-tools", @@ -3045,16 +3045,6 @@ "integrity": "sha512-6aN99yL695Hi9SuIk1oC88l9o0gmxL1nGWWQ/kNy81HigJ0FoaoTXpytCj6ItzgyCEwA9kF1wixsTuv5cjsgng==", "dependencies": [] }, - { - "name": "acorn-jsx-walk", - "version": "2.0.0", - "direct": false, - "scope": "development", - "optional": false, - "license": "MIT", - "integrity": "sha512-uuo6iJj4D4ygkdzd6jPtcxs8vZgDX9YFIkqczGImoypX2fQ4dVImmu3UzA4ynixCIMTrEOWW+95M2HuBaCEOVA==", - "dependencies": [] - }, { "name": "acorn-jsx", "version": "5.3.2", @@ -3067,30 +3057,6 @@ "acorn@8.17.0" ] }, - { - "name": "acorn-loose", - "version": "8.5.2", - "direct": false, - "scope": "development", - "optional": false, - "license": "MIT", - "integrity": "sha512-PPvV6g8UGMGgjrMu+n/f9E/tCSkNQ2Y97eFvuVdJfG11+xdIeDcLyNdC8SHcrHbRqkfwLASdplyR6B6sKM1U4A==", - "dependencies": [ - "acorn@8.17.0" - ] - }, - { - "name": "acorn-walk", - "version": "8.3.5", - "direct": false, - "scope": "development", - "optional": false, - "license": "MIT", - "integrity": "sha512-HEHNfbars9v4pgpW6SO1KSPkfoS0xVOM/9UzkJltjlsHZmJasxg8aXkuZa7SMf8vKGIBhpUsPluQSqhJFCqebw==", - "dependencies": [ - "acorn@8.17.0" - ] - }, { "name": "acorn", "version": "8.17.0", @@ -3324,19 +3290,6 @@ "integrity": "sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==", "dependencies": [] }, - { - "name": "chalk", - "version": "4.1.2", - "direct": false, - "scope": "development", - "optional": false, - "license": "MIT", - "integrity": "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==", - "dependencies": [ - "ansi-styles@4.3.0", - "supports-color@7.2.0" - ] - }, { "name": "check-error", "version": "2.1.3", @@ -3393,16 +3346,6 @@ "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", "dependencies": [] }, - { - "name": "commander", - "version": "15.0.0", - "direct": false, - "scope": "development", - "optional": false, - "license": "MIT", - "integrity": "sha512-z67u4ZhzCL/Tydu1lJARtEZYWbWaN7oYLHbsuzocr6y4N6WZAagG3RQ4FW61V1/0+jImpj293XfrcYnd1qxtPg==", - "dependencies": [] - }, { "name": "convert-source-map", "version": "2.0.0", @@ -3559,35 +3502,6 @@ "integrity": "sha512-N+MeXYoqr3pOgn8xfyRPREN7gHakLYjhsHhWGT3fWAiL4IkAt0iDw14QiiEm2bE30c5XX5q0FtAA3CK5f9/BUg==", "dependencies": [] }, - { - "name": "dependency-cruiser", - "version": "18.1.0", - "direct": true, - "scope": "development", - "optional": false, - "license": "MIT", - "integrity": "sha512-pbsH0gQ15BxXi97SCuMeVgsh8VzYpziGIVaMdnALbVu+TYjSZrW9/nOvsPU+NjHLmJSF9R1UijjoACq6Ne/ybQ==", - "dependencies": [ - "acorn-jsx-walk@2.0.0", - "acorn-jsx@5.3.2", - "acorn-loose@8.5.2", - "acorn-walk@8.3.5", - "acorn@8.17.0", - "commander@15.0.0", - "enhanced-resolve@5.24.2", - "ignore@7.0.6", - "interpret@3.1.1", - "is-installed-globally@1.0.0", - "json5@2.2.3", - "picomatch@4.0.5", - "prompts@2.4.2", - "rechoir@0.8.0", - "safe-regex@2.1.1", - "semver@7.8.5", - "tsconfig-paths-webpack-plugin@4.2.0", - "watskeburt@6.0.0" - ] - }, { "name": "dequal", "version": "2.0.3", @@ -4164,18 +4078,6 @@ "path-scurry@2.0.2" ] }, - { - "name": "global-directory", - "version": "4.0.1", - "direct": false, - "scope": "development", - "optional": false, - "license": "MIT", - "integrity": "sha512-wHTUcDUoZ1H5/0iVqEudYW4/kAlN5cZ3j/bXn0Dpbizl9iaUVeWSHqiOjsgk6OW2bkLclbBjzewBz6weQ1zA2Q==", - "dependencies": [ - "ini@4.1.1" - ] - }, { "name": "globals", "version": "17.7.0", @@ -4295,16 +4197,6 @@ "integrity": "sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==", "dependencies": [] }, - { - "name": "ignore", - "version": "7.0.6", - "direct": false, - "scope": "development", - "optional": false, - "license": "MIT", - "integrity": "sha512-BAg6QkE8W+TuQLrrw0Ugr7HegXduRuuj8/ti2kSOc+jz1dmx8/WNcjr6XGnq5YpDWxFwwaavqD0+jIUOKelTsw==", - "dependencies": [] - }, { "name": "import-meta-resolve", "version": "4.2.0", @@ -4335,26 +4227,6 @@ "integrity": "sha512-EdDDZu4A2OyIK7Lr/2zG+w5jmbuk1DVBnEwREQvBzspBJkCEbRa8GxU1lghYcaGJCnRWibjDXlq779X1/y5xwg==", "dependencies": [] }, - { - "name": "ini", - "version": "4.1.1", - "direct": false, - "scope": "development", - "optional": false, - "license": "ISC", - "integrity": "sha512-QQnnxNyfvmHFIsj7gkPcYymR8Jdw/o7mp5ZFihxn6h8Ci6fh3Dx4E1gPjpQEpIuPo9XVNY/ZUwh4BPMjGyL01g==", - "dependencies": [] - }, - { - "name": "interpret", - "version": "3.1.1", - "direct": false, - "scope": "development", - "optional": false, - "license": "MIT", - "integrity": "sha512-6xwYfHbajpoF0xLW+iwLkhwgvLoZDfjYfoFNu8ftMoXINzwuymNLd9u/KmwtdT2GbR+/Cz66otEGEVVUHX9QLQ==", - "dependencies": [] - }, { "name": "is-core-module", "version": "2.16.2", @@ -4421,19 +4293,6 @@ "is-docker@3.0.0" ] }, - { - "name": "is-installed-globally", - "version": "1.0.0", - "direct": false, - "scope": "development", - "optional": false, - "license": "MIT", - "integrity": "sha512-K55T22lfpQ63N4KEN57jZUAaAYqYHEe8veb/TycJRk9DdSCLLcovXz/mL6mOnhQaZsQGwPhuFopdQIlqGSEjiQ==", - "dependencies": [ - "global-directory@4.0.1", - "is-path-inside@4.0.0" - ] - }, { "name": "is-node-process", "version": "1.2.0", @@ -4444,16 +4303,6 @@ "integrity": "sha512-Vg4o6/fqPxIjtxgUH5QLJhwZ7gW5diGCVlXpuUfELC62CuxM1iHcRe51f2W1FDy04Ai4KJkagKjx3XaqyfRKXw==", "dependencies": [] }, - { - "name": "is-path-inside", - "version": "4.0.0", - "direct": false, - "scope": "development", - "optional": false, - "license": "MIT", - "integrity": "sha512-lJJV/5dYS+RcL8uQdBDW9c9uWFLLBNRyFhnAKXw5tVqLlKZ4RMGZKv+YQ/IA3OhD+RpbJa1LLFM1FQPGyIXvOA==", - "dependencies": [] - }, { "name": "is-potential-custom-element-name", "version": "1.0.1", @@ -4657,16 +4506,6 @@ "json-buffer@3.0.1" ] }, - { - "name": "kleur", - "version": "3.0.3", - "direct": false, - "scope": "development", - "optional": false, - "license": "MIT", - "integrity": "sha512-eTIzlVOSUR+JxdDFepEYcBMtZ9Qqdef+rnzWdRZuMbOywu5tO2w2N7rqjoANZ5k9vywhL6Br1VRjUIgTQx4E8w==", - "dependencies": [] - }, { "name": "levn", "version": "0.4.1", @@ -5498,19 +5337,6 @@ "react-is@17.0.2" ] }, - { - "name": "prompts", - "version": "2.4.2", - "direct": false, - "scope": "development", - "optional": false, - "license": "MIT", - "integrity": "sha512-NxNv/kLguCA7p3jE8oL2aEBsrJWgAakBpgmgK6lpPWV+WuOmY6r2/zbAVnP+T8bQlA0nzHXSJSJW0Hq7ylaD2Q==", - "dependencies": [ - "kleur@3.0.3", - "sisteransi@1.0.5" - ] - }, { "name": "punycode", "version": "2.3.1", @@ -5632,18 +5458,6 @@ "tslib@2.8.1" ] }, - { - "name": "rechoir", - "version": "0.8.0", - "direct": false, - "scope": "development", - "optional": false, - "license": "MIT", - "integrity": "sha512-/vxpCXddiX8NGfGO/mTafwjq4aFa/71pvamip0++IQk3zG8cbCj0fifNPrjjF1XMXUne91jL9OoxmdykoEtifQ==", - "dependencies": [ - "resolve@1.22.12" - ] - }, { "name": "redent", "version": "3.0.0", @@ -5657,16 +5471,6 @@ "strip-indent@3.0.0" ] }, - { - "name": "regexp-tree", - "version": "0.1.27", - "direct": false, - "scope": "development", - "optional": false, - "license": "MIT", - "integrity": "sha512-iETxpjK6YoRWJG5o6hXLwvjYAoW+FEZn9os0PD/b6AP6xQwsa/Y7lCVgIixBbUPMfhu+i2LtdeAqVTgGlQarfA==", - "dependencies": [] - }, { "name": "require-directory", "version": "2.1.1", @@ -5750,18 +5554,6 @@ "integrity": "sha512-DPe5pVFaAsinSaV6QjQ6gdiedWDcRCbUuiQfQa2wmWV7+xC9bGulGI8+TdRmoFkAPaBXk8CrAbnlY2ISniJ47Q==", "dependencies": [] }, - { - "name": "safe-regex", - "version": "2.1.1", - "direct": false, - "scope": "development", - "optional": false, - "license": "MIT", - "integrity": "sha512-rx+x8AMzKb5Q5lQ95Zoi6ZbJqwCLkqi3XuJXp5P3rT8OEc6sZCJG5AE5dU3lsgRr/F4Bs31jSlVN+j5KrsGu9A==", - "dependencies": [ - "regexp-tree@0.1.27" - ] - }, { "name": "saxes", "version": "6.0.0", @@ -5866,16 +5658,6 @@ "integrity": "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==", "dependencies": [] }, - { - "name": "sisteransi", - "version": "1.0.5", - "direct": false, - "scope": "development", - "optional": false, - "license": "MIT", - "integrity": "sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==", - "dependencies": [] - }, { "name": "source-map-js", "version": "1.2.2", @@ -6214,21 +5996,6 @@ "integrity": "sha512-JfJeIHke7y2egdGGgRAvpCwYFUsHlM2gPcrVOxFkznt/4uzQ7HFmvE63iFHVLBJNDuyDOQgijDK/tXH/f6Msjg==", "dependencies": [] }, - { - "name": "tsconfig-paths-webpack-plugin", - "version": "4.2.0", - "direct": false, - "scope": "development", - "optional": false, - "license": "MIT", - "integrity": "sha512-zbem3rfRS8BgeNK50Zz5SIQgXzLafiHjOwUAvk/38/o1jHn/V5QAgVUcz884or7WYcPaH3N2CIfUc2u0ul7UcA==", - "dependencies": [ - "chalk@4.1.2", - "enhanced-resolve@5.24.2", - "tapable@2.3.3", - "tsconfig-paths@4.2.0" - ] - }, { "name": "tsconfig-paths", "version": "4.2.0", @@ -6442,16 +6209,6 @@ "xml-name-validator@5.0.0" ] }, - { - "name": "watskeburt", - "version": "6.0.0", - "direct": false, - "scope": "development", - "optional": false, - "license": "MIT", - "integrity": "sha512-jfiuDABaxSkC71T6oZ3vCS99roYkSHm/+As+G0Dz8taAHQb+SJBvLEm5RlsgG71XdfAj3rv7eudUBTgwcQUPlQ==", - "dependencies": [] - }, { "name": "webidl-conversions", "version": "8.0.1", 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 23a0baa9..04c882b5 100644 --- a/docs/ledger/estimates.jsonl +++ b/docs/ledger/estimates.jsonl @@ -1,3 +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 289bb3e5..07093512 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 기록). 생성 명령이 만든다. ① **정할 것** @@ -815,4 +816,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 f2fbdc95..529fbabf 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: