diff --git a/.dependency-cruiser.json b/.dependency-cruiser.json index 1e022fd6..7ab151ca 100644 --- a/.dependency-cruiser.json +++ b/.dependency-cruiser.json @@ -2,6 +2,7 @@ "forbidden": [ { "name": "domain-is-framework-neutral", + "comment": "domain holds framework-neutral models and pure policies. Keep the dependency out: move the code to application, or pass the value in from there.", "severity": "error", "from": { "path": "^src/domain" @@ -12,6 +13,7 @@ }, { "name": "application-does-not-know-concrete-runtime", + "comment": "application owns use cases and the ports they need. Declare a port under src/application/ports and let src/bootstrap pass the concrete adapter.", "severity": "error", "from": { "path": "^src/application" @@ -22,6 +24,7 @@ }, { "name": "presentation-does-not-know-adapters", + "comment": "§4. Presentation talks to application ports, not concrete adapters, the composition root or the TanStack runtime. Exception: src/presentation/adapters/query is the TanStack Query binding, the one place @tanstack is imported (docs/architecture/frontend-ports-adapters-and-boundaries.md). It needs @tanstack only; concrete-adapters-compose-only-in-bootstrap still keeps it off src/adapters. Owner: frontend-platform. Revisit if the binding moves out of presentation.", "severity": "error", "from": { "path": "^src/presentation/(?!adapters/query)" @@ -32,6 +35,7 @@ }, { "name": "page-templates-own-layout-only", + "comment": "Page templates own layout only. Take data and actions as props from the page that uses the template.", "severity": "error", "from": { "path": "^src/presentation/templates" @@ -42,6 +46,7 @@ }, { "name": "icon-vendor-is-facade-only", + "comment": "VD-05. lucide-react is imported by the icon vendor facade only; product code uses the semantic icons from the design-system index, so replacing the vendor touches one file.", "severity": "error", "from": { "path": "^src", @@ -51,8 +56,34 @@ "path": "^lucide-react$" } }, + { + "name": "zod-is-reached-through-contracts-zod", + "comment": "F-7 (13-08). src/contracts/zod.ts sets zod jitless before any schema is built, so the production CSP never sees zod's Function probe. Schema code imports z from there.", + "severity": "error", + "from": { + "path": "^src", + "pathNot": "^src/contracts/zod\\.ts$" + }, + "to": { + "path": "^zod$" + } + }, + { + "name": "design-system-is-reached-through-its-index", + "comment": "VD-05, 12-08. Code outside src/presentation/design-system imports its public index.ts only, so the primitives can change behind it. Named facades: src/presentation/components/ui/*.ts re-export the canonical primitives under their pre-VD-05 paths (VD-05 Rollback). Exception: src/presentation/templates/page-templates.tsx reads PaginationLandmarkContext, which index.ts does not export. Owner: frontend-platform. Revisit: export it from index.ts or move the page templates into the design system.", + "severity": "error", + "from": { + "path": "^src/", + "pathNot": "^src/presentation/(design-system/|components/ui/[^/]+\\.ts$|templates/page-templates\\.tsx$)" + }, + "to": { + "path": "^src/presentation/design-system/", + "pathNot": "^src/presentation/design-system/index\\.ts$" + } + }, { "name": "adapters-do-not-know-presentation", + "comment": "An adapter implements an application port. It never imports UI or the composition root; pass what it needs through the port or its factory arguments.", "severity": "error", "from": { "path": "^src/adapters" @@ -63,6 +94,7 @@ }, { "name": "feature-domain-is-framework-neutral", + "comment": "A feature's domain is framework-neutral, like src/domain. Move the code to the feature's application, or pass the value in from there.", "severity": "error", "from": { "path": "^src/features/[^/]+/domain" @@ -73,6 +105,7 @@ }, { "name": "feature-application-does-not-know-runtime", + "comment": "A feature's application declares the ports it needs. Put the port in the feature's application and implement it in the feature's adapters/; bootstrap wires the two.", "severity": "error", "from": { "path": "^src/features/[^/]+/application" @@ -83,6 +116,7 @@ }, { "name": "feature-presentation-does-not-know-outbound-adapters", + "comment": "Feature presentation calls its application API. The feature's adapters/ are wired by bootstrap, so import the application facade instead.", "severity": "error", "from": { "path": "^src/features/[^/]+/presentation" @@ -93,6 +127,7 @@ }, { "name": "feature-adapters-do-not-know-presentation", + "comment": "A feature adapter implements the feature's ports and never imports UI or the composition root. Pass what it needs through the port.", "severity": "error", "from": { "path": "^src/features/[^/]+/adapters" @@ -103,6 +138,7 @@ }, { "name": "concrete-adapters-compose-only-in-bootstrap", + "comment": "Only src/bootstrap constructs concrete adapters. Depend on the application port or facade; bootstrap composes the adapter behind it.", "severity": "error", "from": { "path": "^src/(domain|application|presentation|contracts)" @@ -113,7 +149,7 @@ }, { "name": "external-contract-package-single-import-path", - "comment": "§4.1: a generated service package may only be imported from src/features//contracts/*-contract-contribution.ts", + "comment": "§4.1: a generated service package may only be imported from src/features//contracts/*-contract-contribution.ts. Owner: frontend-platform.", "severity": "error", "from": { "path": "^src", @@ -125,7 +161,7 @@ }, { "name": "presentation-does-not-fetch-directly", - "comment": "§9.2 / appendix B: a page or hook never opens a socket, worker or HTTP adapter itself", + "comment": "§9.2 / appendix B: a page or hook never opens a socket, worker or HTTP adapter itself. Call the application API; bootstrap composes the adapter behind it.", "severity": "error", "from": { "path": "^src/(presentation|features/[^/]+/presentation)" @@ -134,9 +170,20 @@ "path": "^src/adapters/(http|realtime|service-worker|web-worker|storage)" } }, + { + "name": "unselected-realtime-runtime-is-not-composed", + "comment": "§9.2 / 12-10. Realtime and Web Push are NOT_SELECTED in the template (src/features/installed-runtime-capabilities.ts), so the composition root and the installed-feature registries do not import their concrete adapters. A project that selects one replaces this rule when it wires the runtime. Owner: frontend-platform.", + "severity": "error", + "from": { + "path": "^src/(bootstrap/|features/installed-feature-)" + }, + "to": { + "path": "^src/adapters/(realtime|web-push)/" + } + }, { "name": "generic-worker-has-no-network-or-credentials", - "comment": "§16.13 / §21.10: a CPU worker never imports HTTP, realtime or auth", + "comment": "§16.13 / §21.10: a CPU worker never imports HTTP, realtime or auth. Do the network call on the page side and post the data to the worker.", "severity": "error", "from": { "path": "^src/adapters/web-worker" @@ -180,7 +227,7 @@ }, { "name": "generic-presentation-does-not-compose-the-product", - "comment": "§4 / §9. Which features are installed is a product decision that belongs to bootstrap. Generic presentation reads the installed registries directly today; the paths below are the exact set that does so, frozen so the coupling cannot spread while the assembly is lifted into bootstrap.", + "comment": "§4 / §9. Which features are installed is a product decision that belongs to bootstrap. Exception: the generic presentation modules in pathNot read the installed registries today. The list names exact files, so a new module that reads a registry fails the gate. Owner: frontend-platform. Revisit when the assembly is lifted into bootstrap; remove each file from the list as it stops reading the registries.", "severity": "error", "from": { "path": "^src/presentation/", @@ -192,7 +239,7 @@ }, { "name": "adapters-do-not-know-other-concrete-adapters", - "comment": "docs/architecture/layers.md §4: a concrete adapter never depends on another concrete adapter. Only the adapter kernel is shared — `src/adapters/platform` (clock, abort primitive, capacity guard) and the browser-data result helpers. `query-cache` still reads two collaborator types from `cross-context-invalidation`; that edge is named here rather than left silent, and closes when those types are lifted to a port.", + "comment": "docs/architecture/layers.md §4: a concrete adapter never depends on another concrete adapter. The adapter kernel is shared on purpose and any adapter may import it: src/adapters/platform/** (clock, abort primitive, capacity guard), src/adapters/browser-file-storage/result.ts (browser-data result helpers) and src/adapters/cross-context-invalidation/index.ts (the cross-context invalidation transport and its types). Owner: frontend-platform. No new file-level exception is added here; a new shared primitive goes into src/adapters/platform/.", "severity": "error", "from": { "path": "^src/adapters/([^/]+)/" @@ -204,7 +251,7 @@ }, { "name": "adapter-groups-are-reached-through-their-barrel", - "comment": "어댑터 그룹의 공개 표면은 그 그룹의 index.ts다. 그룹 바깥(bootstrap, features, presentation)은 배럴만 import한다. 배럴이 없던 시절 bootstrap은 어댑터 내부 파일 15곳을 직접 겨눴고, 그래서 어떤 파일이 공개이고 어떤 파일이 내부 헬퍼인지 아무 데도 적혀 있지 않았다. 출발점에서 src/adapters를 뺀 이유는 어댑터끼리의 간선은 바로 위 adapters-do-not-know-other-concrete-adapters가 이미 담당하고, 커널(platform/**)은 파일 단위로 공유되기 때문이다 — scripts/check-adapter-inventory.ts가 네 소비자에게 platform/abortable-operation.ts로 해석되는 specifier를 직접 요구한다. 도착점에서 1단계 중첩 index.ts를 허용한 이유는 storage/indexeddb와 storage/opfs가 각자 독립적으로 제거 가능한 런타임이고(scripts/test-browser-file-storage-runtime-removal.ts), 그래서 각자의 배럴이 곧 경계이기 때문이다.", + "comment": "어댑터 그룹의 공개 표면은 그 그룹의 index.ts다. 그룹 바깥(bootstrap, features, presentation)은 배럴만 import한다. 배럴이 없던 시절 bootstrap은 어댑터 내부 파일 15곳을 직접 겨눴고, 그래서 어떤 파일이 공개이고 어떤 파일이 내부 헬퍼인지 아무 데도 적혀 있지 않았다. 출발점에서 src/adapters를 뺀 이유는 어댑터끼리의 간선은 바로 위 adapters-do-not-know-other-concrete-adapters가 이미 담당하고, 커널(platform/**)은 파일 단위로 공유되기 때문이다 — scripts/check-adapter-inventory.ts가 네 소비자에게 platform/abortable-operation.ts로 해석되는 specifier를 직접 요구한다. 예외: 도착점에서 storage/indexeddb/index.ts와 storage/opfs/index.ts만 서브배럴로 허용한다. 두 폴더는 browser-file-storage 번들의 런타임이고, 제거 드릴(scripts/test-browser-file-storage-runtime-removal.ts)은 그 번들 전체(browser-file-storage, browser-files, browser-transfer, cache-storage, storage/indexeddb, storage/opfs)를 함께 지운다. 최상위 storage 배럴(Web Storage)은 그 뒤에도 남아야 하므로 두 폴더를 재수출하지 않고, 그래서 각 서브배럴이 그 런타임의 공개 경계다. 다른 2단계 index.ts는 공개 배럴이 아니다(리뷰 12-07). 담당: frontend-platform. 재검토: 새 런타임을 따로 제거할 수 있게 만들 때 그 서브배럴을 이 목록에 추가한다.", "severity": "error", "from": { "path": "^src/", @@ -212,7 +259,7 @@ }, "to": { "path": "^src/adapters/[^/]+/", - "pathNot": "^src/adapters/[^/]+/index\\.ts$|^src/adapters/[^/]+/[^/]+/index\\.ts$" + "pathNot": "^src/adapters/[^/]+/index\\.ts$|^src/adapters/storage/(indexeddb|opfs)/index\\.ts$" } }, { @@ -239,6 +286,30 @@ "pathNot": "^src/contexts/$1/" } }, + { + "name": "feature-and-app-roots-do-not-reach-adapters", + "comment": "12-03. The graph checks one edge at a time, so a module that presentation may import must not re-export a concrete adapter: presentation would then reach it with every direct rule passing. That covers the files outside a feature's layer folders (src/features/*.ts, src/features//*.ts), src/contexts and src/apps. Inside a feature, only its adapters/ folder reaches src/adapters; the product composes adapters in bootstrap. Exception: src/features/feature-adapter-contribution.ts imports the InstalledHttpOperationExecutor type that bootstrap hands to feature adapters (type only). Owner: frontend-platform. Revisit when that type moves to an application port.", + "severity": "error", + "from": { + "path": "^src/(features/[^/]+\\.tsx?$|features/[^/]+/[^/]+\\.tsx?$|contexts/|apps/)", + "pathNot": "^src/features/feature-adapter-contribution\\.ts$" + }, + "to": { + "path": "^src/adapters/" + } + }, + { + "name": "presentation-does-not-import-apps-or-contexts", + "comment": "12-03. Apps and contexts compose features, including their runtime, so presentation importing them is a path around presentation-does-not-know-adapters. Exception: src/presentation/routes/app-router.tsx mounts the deployable app's route tree (src/apps/template-app.ts). Owner: frontend-platform. Revisit when the router is assembled in bootstrap together with the frozen generic-presentation-does-not-compose-the-product list.", + "severity": "error", + "from": { + "path": "^src/(presentation/|features/[^/]+/presentation/)", + "pathNot": "^src/presentation/routes/app-router\\.tsx$" + }, + "to": { + "path": "^src/(apps|contexts)/" + } + }, { "name": "observability-vendors-live-behind-adapters", "comment": "Spec §24. Features, platform, application, domain, contracts and presentation emit observability only through the provider-neutral TelemetryPort. A vendor telemetry SDK may be imported only by an adapter-side transport under src/adapters.", @@ -253,7 +324,7 @@ }, { "name": "platform-kernel-is-product-neutral", - "comment": "Spec §4. src/platform holds product-neutral primitives (budgets, execution, telemetry pipeline, validation, error envelopes). It never reaches up into a concrete feature, context, adapter, bootstrap or presentation module. Routing composes deployable-app descriptors by type and is the one named exception.", + "comment": "Spec §4. src/platform holds product-neutral primitives (budgets, execution, telemetry pipeline, validation, error envelopes). It never reaches up into a concrete feature, context, adapter, bootstrap or presentation module. Exception: src/platform/routing composes deployable-app descriptors by type. Owner: frontend-platform. Revisit if routing gains a product-specific import.", "severity": "error", "from": { "path": "^src/platform/", @@ -265,33 +336,12 @@ }, { "name": "no-circular-dependencies", + "comment": "A cycle makes the modules impossible to load or remove one at a time. Move the shared part into a lower module that both import.", "severity": "error", "from": {}, "to": { "circular": true } } - ], - "options": { - "doNotFollow": { - "path": "node_modules" - }, - "exclude": { - "path": "^(dist|artifacts|tests/fixtures)" - }, - "enhancedResolveOptions": { - "exportsFields": [ - "exports" - ], - "conditionNames": [ - "import", - "require", - "node", - "default" - ] - }, - "tsConfig": { - "fileName": "tsconfig.app.json" - } - } + ] } diff --git a/.env.example b/.env.example index cae5252d..47d62975 100644 --- a/.env.example +++ b/.env.example @@ -6,7 +6,7 @@ # Runtime configuration — API endpoints, auth mode, telemetry, capability # switches — is NOT here. It lives in `config/runtime/.json` and is # materialized into `dist/config.json` at build time, so it can be changed -# without rebuilding. See docs/architecture/layers.md. +# without rebuilding. See the "Runtime configuration" section of README.md. # # Copy to `.env.local` (git-ignored) to override locally. diff --git a/.gitea/workflows/quality-gates.yml b/.gitea/workflows/quality-gates.yml index a718a9e2..273556ee 100644 --- a/.gitea/workflows/quality-gates.yml +++ b/.gitea/workflows/quality-gates.yml @@ -3,7 +3,7 @@ name: frontend-quality-gates on: push: - branches: [develop] + branches: [main, develop] tags: ["v*"] pull_request: workflow_dispatch: @@ -83,16 +83,14 @@ jobs: if: ${{ startsWith(gitea.ref, 'refs/tags/v') || (gitea.event_name == 'workflow_dispatch' && (inputs.stage == 'release' || inputs.stage == 'production' || inputs.stage == 'field')) }} runs-on: ubuntu-latest timeout-minutes: 45 - env: - HOSTING_BASE_URL: "${{ vars.HOSTING_BASE_URL }}" strategy: fail-fast: false matrix: include: - { gate: FE-GATE-012, name: bundle, browser: false } - { gate: FE-GATE-014, name: config-compatibility, browser: false } - - { gate: FE-GATE-019, name: hosting-header, browser: false } - { gate: FE-GATE-026, name: lab-performance, browser: true } + - { gate: FE-GATE-028, name: manual-accessibility-review, browser: false } steps: - uses: https://github.com/actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 with: @@ -142,6 +140,8 @@ jobs: corepack pnpm install --frozen-lockfile --ignore-scripts - name: Build candidate once and verify local evidence run: corepack pnpm ci:gate -- FE-GATE-015 + - name: Admit the candidate to the declared release target + run: corepack pnpm ci:gate -- FE-GATE-027 - name: Archive and validate the exact candidate file set id: candidate run: | @@ -368,15 +368,18 @@ jobs: production_gate: name: "${{ matrix.gate }} / ${{ matrix.name }}" - needs: promotion + needs: [immutable_build, promotion] if: ${{ gitea.event_name == 'workflow_dispatch' && (inputs.stage == 'production' || inputs.stage == 'field') }} runs-on: ubuntu-latest timeout-minutes: 45 + env: + HOSTING_BASE_URL: "${{ vars.HOSTING_BASE_URL }}" + CANDIDATE_ARCHIVE_SHA256: "${{ needs.immutable_build.outputs.archive_sha256 }}" strategy: fail-fast: false matrix: include: - - { gate: FE-GATE-016, name: rollback-drill } + - { gate: FE-GATE-019, name: hosting-header } - { gate: FE-GATE-021, name: runbook-boot-config } - { gate: FE-GATE-022, name: runbook-chunk-mismatch } - { gate: FE-GATE-023, name: runbook-api-degradation } @@ -393,6 +396,13 @@ jobs: run: | corepack enable corepack pnpm install --frozen-lockfile --ignore-scripts + - name: Download promoted release + uses: https://github.com/ChristopherHX/gitea-download-artifact@75635f32b4c1c41c4b3d64e8f85210112ed4c9c7 + with: + name: "promoted-release-${{ gitea.run_id }}-${{ gitea.run_attempt }}" + path: .release/promoted + - name: Verify and extract the candidate through one inode-bound operation + run: node scripts/verify-ci-candidate-archive.ts --archive ".release/promoted/release-candidate.tar.gz" --extract-to ".release/promoted-release" - name: Run blocking gate run: corepack pnpm ci:gate -- ${{ matrix.gate }} - name: Upload production gate evidence diff --git a/.npmrc b/.npmrc index d9ca8860..bb2997b5 100644 --- a/.npmrc +++ b/.npmrc @@ -1,2 +1,2 @@ -engine-strict=true -save-exact=true +# pnpm 11 reads engineStrict and saveExact from pnpm-workspace.yaml, not from +# this file (review 13-09). Keep only npm-level settings such as registry auth here. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..b017977c --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,88 @@ +# 변경 이력 + +이 템플릿을 복사해 쓰는 프로젝트가 원본의 수정을 골라 가져갈 때 보는 문서다. +가져오는 방법은 `README.md`의 "Updating a copied project" 절에 있다. + +- 버전은 git 태그 `vX.Y.Z`로 식별한다. 태그 사이의 변경을 여기 적는다. +- **[보안]** 복사한 프로젝트도 가져가야 하는 보안·개인정보 수정이다. +- **[계약]** 백엔드, 배포 설정, CI, 또는 기능 코드가 함께 바뀌어야 하는 변경이다(헤더, 변수, 게이트, 공개 포트). +- 표시가 없으면 템플릿 안에서 끝나는 수정이다. +- 괄호 안 ID는 리뷰 발견 ID다. 근거와 재현 조건은 해당 리뷰 문서에 있다. +- 커밋 해시는 브랜치 `fix/maturity-review-2026-09-25` 기준이다. 병합 방식에 따라 `main`에서는 해시가 다를 수 있으니 ID로 찾는다(`git log --grep '03-03'`). + +## 0.2.0 — 태그 `v0.2.0` (2026-09-27) + +2026-09-25 성숙도 리뷰(`docs/reviews/2026-09-25-maturity-review/`) 수정 묶음이다. +기준은 `main` `4626b73`이다. `package.json`의 `version`은 `0.2.0`이다. + +### 보안·계약 변경 + +먼저 볼 항목이다. 복사한 프로젝트가 이 경로를 고쳤다면 충돌을 직접 풀어야 한다. + +| 표시 | 변경 | 영향 경로 | 커밋 | +|---|---|---|---| +| [계약] | 모든 V3 HTTP 요청이 논리 실행마다 `x-correlation-id` 헤더를 하나 보낸다. 다른 origin API는 preflight `Access-Control-Allow-Headers`에 이 헤더를 넣어야 요청이 나간다. 응답의 같은 헤더를 읽으려면 `Access-Control-Expose-Headers`에도 넣는다 (03-03) | `src/adapters/http/http-execution-v3.ts`, `src/adapters/http/feature-http-binding.ts`, `src/bootstrap/runtime-adapters.ts`, `docs/operations/api-contract-and-server-state-recovery.md` | `c5da3cf`, `f0a6495` | +| [계약] | 결과를 모르는 쓰기(응답 유실)를 다시 보낼 때 처음의 멱등 키를 그대로 쓴다. 백엔드는 같은 키의 재전송을 한 번만 적용해야 한다 (03-01, 08-03) | `src/presentation/adapters/query/application-query.ts`, `src/presentation/forms/use-app-form.ts`, `src/presentation/components/async-surface.tsx` | `dfb1b9e` | +| [계약] | 명령의 401/403/429를 기능 패키지가 분류할 수 있다(`classifyStatus`, 선택 필드). 재로그인이 먼저다 (03-02) | `src/adapters/http/http-effect-certainty.ts`, `src/adapters/http/http-execution-v3.ts`, `src/contracts/errors.ts`, `src/contracts/external-contract-runtime.ts` | `2afee67` | +| [계약] | 422 problem body의 필드 오류(`path`, `code`)를 폼까지 전달한다 (03-04) | `src/adapters/http/feature-http-binding.ts`, `src/features/reference-feature/contracts/reference-schemas.ts` | `479acd5` | +| [계약] | 텔레메트리 수집기 이벤트마다 `build_id`, `release_id`가 붙는다. 한 번에 보내는 본문은 60KiB 아래로 나뉜다 (13-11, 03-05) | `src/adapters/telemetry/telemetry-collector.ts`, `src/bootstrap/runtime-adapters.ts` | `43e47f4`, `e14c613` | +| [보안] | 번들이 읽지 않는 `VITE_*` 값까지 통째로 넣던 문제를 고쳤다. 값은 키로만 읽고, `ENV_REGISTRY`에 없는 `VITE_*` 이름은 빌드를 멈춘다 (13-06) | `src/contracts/env.ts`, `vite.config.ts`, `eslint.config.ts` | `2ec59ad` | +| [보안] | 로그아웃·계정 삭제 purge가 손상된 IndexedDB 때문에 열리지 않으면 그 파티션의 DB를 지운다. OPFS purge는 남은 chunk를 바로 지운다 (05-03, 05-04) | `src/adapters/platform/indexeddb-connection.ts`, `src/adapters/storage/indexeddb/indexeddb-runtime.ts`, `src/adapters/storage/opfs/opfs-byte-store-adapter.ts`, `src/application/ports/browser-file-storage/` | `3e37fbf`, `6ab564f` | +| [계약] | `RELEASE_TARGET`이 `APP_PROFILE`과 다르면 배포 승인이 거절된다 (12-02, 13-01) | `scripts/check-release-admission.ts`, `.gitea/workflows/quality-gates.yml` | `239b22a` | +| [계약] | 설정·매니페스트 URL이 `VITE_ROUTER_BASE_PATH`를 따른다. base 밖의 설정 URL은 빌드를 멈춘다 (13-07) | `scripts/generate-runtime-config.ts`, `src/contracts/env.ts`, `vite.config.ts` | `e215c84` | +| [계약] | `VITE_PRODUCT_FEATURES`는 생성기에서 적용되고, 모르는 기능 ID는 빌드를 멈춘다 (09-02) | `scripts/generate-product-feature-index.ts`, `src/contracts/product-features.ts` | `a8111f7` | +| [계약] | `src/features//`에 `feature-module.ts`도 `NOT_INSTALLED` 표식도 없으면 생성기가 실패한다. 기능 제거 검사는 `--feature=`를 받는다 (09-07, 14-03) | `scripts/generate-product-feature-index.ts`, `scripts/test-sample-removal.ts`, `config/contracts/registry-governance.json`, `docs/architecture/starter-experience.md` | `ad0e83c` | +| [계약] | 기능 루트·context·app 파일은 `src/adapters`를 import할 수 없다. presentation은 app·context를 import할 수 없다(`app-router.tsx` 예외) (12-03) | `scripts/check-architecture.ts`, `.dependency-cruiser.json`, `docs/architecture/layers.md` | `f8b6a36` | +| [계약] | CI 계약의 게이트 수·해시가 `config/ci/contract-baseline.json`으로 옮겨졌다. 게이트를 바꾸면 `update:ci-contract-baseline`로 갱신한다 (14-02) | `config/ci/contract-baseline.json`, `scripts/check-ci-contract.ts` | `0114b1e` | +| [계약] | 모든 테스트 파일은 어떤 게이트가 돌리거나 `config/ci/ungated-tests.json`에 이유가 있어야 한다 (12-04, 09-11, 11-03) | `config/ci/gates.json`, `config/ci/ungated-tests.json`, `scripts/lib/ungated-tests.ts` | `840de45`, `45ee231` | +| [계약] | 게이트 판정 변경: 서명된 수동 접근성 검토는 release 게이트 FE-GATE-028로, runbook drill은 관측하지 못한 단계를 `UNVERIFIED`(exit 3)로, FE-GATE-016은 폐지, FE-GATE-019는 배포 뒤 production 단계에서 돈다 (08-06, 11-01, 13-03, 13-05) | `config/ci/gates.json`, `.gitea/workflows/quality-gates.yml`, `scripts/drill-runbook.ts`, `docs/operations/ci-quality-gates.md` | `7298275`, `7f889a6`, `a263d8c` | +| [계약] | `engineStrict`, `saveExact`를 `pnpm-workspace.yaml`로 옮겼다. 지원하지 않는 Node에서 설치가 실패한다 (13-09) | `pnpm-workspace.yaml`, `.npmrc` | `a5dc851` | +| [계약] | 폼 저장 실패에 재로그인·권한 없음·나중에 재시도 상태가 따로 생겼다 (08-01) | `src/presentation/forms/form-contracts.ts`, `src/presentation/forms/use-app-form.ts`, `src/presentation/forms/form-components.tsx` | `9894a70` | +| [계약] | browser-transfer 포트: `upload()` 실패의 recovery 값이 다섯 개로 정리됐고, 완료된 업로드는 `resourceId`를 잃지 않는다. 시간 제한이 바이트 수에 비례한다 (01-01~01-11). file-transfer recipe를 쓰는 프로젝트만 해당 | `src/application/ports/browser-transfer/`, `src/adapters/browser-transfer/` | `648fe4e`, `7b2cefb`, `5a6665a`, `426b6b8` 외 | +| [계약] | IndexedDB·OPFS 포트: 미래 스키마는 `INCOMPATIBLE`, 빈 receipt는 없음으로 본다 (05-01~05-14). offline-indexeddb recipe를 쓰는 프로젝트만 해당 | `src/application/ports/browser-file-storage/`, `src/adapters/storage/` | `7f45afa`, `47cf040`, `8fc816e` 외 | +| [계약] | 외부 세션 owner의 `readSubject()`와 `SessionGateway.getSubject()`가 필수가 됐다. `readSubject`가 없는 owner는 `integration-failed`로 닫힌다. 토큰 갱신마다 서버 상태 캐시가 비워지던 문제를 막는다 | `src/adapters/auth/external-session-adapter.ts`, `src/application/ports/`, `docs/architecture/starter-experience.md` | `c6300e9` | +| [보안] | 운영 CSP(`unsafe-eval` 없음) 아래에서 zod가 eval을 시험하지 않는다. `src/`의 코드는 zod를 `src/contracts/zod.ts`로만 가져온다(dependency-cruiser 규칙) (13-08, F-7) | `src/contracts/zod.ts`, `.dependency-cruiser.json`, `tests/e2e/production-csp.spec.ts` | `9dc95ca` | +| [계약] | 레지스트리 호환성 분류기가 모르는 스키마 변경을 breaking으로 본다. 런타임 설정 스키마도 기준선과 비교한다(FE-GATE-014) (07-02, 13-10) | `src/contracts/compatibility.ts`, `scripts/check-registries.ts`, `config/contracts/` | `17d617a` | +| [계약] | 오류 레지스트리에서 읽지 않는 필드를 뺐다. 호환 별칭과 V1 reader에 `@deprecated`와 제거 조건을 붙였다 (07-04, 07-07) | `src/contracts/errors.ts`, `src/contracts/` | `aff5f43`, `9e616d3` | +| [계약] | staging·production 빌드는 `VITE_BUILD_ID`가 없으면 실패한다 (13-15, F-6) | `scripts/generate-runtime-config.ts`, `src/contracts/env.ts` | `063375e` | +| [계약] | Service Worker 빌드가 `public/config.json` 대신 프로필에서 만든 `dist/config.json`을 읽고, `APP_ENV`가 `APP_PROFILE`과 다르면 빌드를 멈춘다 (06-10, F-8) | `vite.service-worker.config.ts`, `scripts/lib/service-worker-build-input.ts` | `cefb0b2` | +| [계약] | Web Push: 탭 사이 구독 제어를 Web Lock으로 직렬화하고, 새 세션이 다른 계정의 push fence를 넘겨받는다. `REMOVE_REGISTRATION`은 스스로 등록을 해지하는 worker를 배포한다 (06-02, 06-06, 06-03) | `src/adapters/web-push/`, `scripts/lib/self-unregistering-service-worker.ts`, `docs/runbooks/` | `e6c683e`, `996a959`, `9f2305a` | +| [계약] | realtime: 세션이 끝날 때마다 재시도 예산을 초기화하고 offline 동안 멈춘다. SSE `Retry-After`를 따른다. 등록되지 않은 이벤트 종류는 registry mismatch로 끝난다 (04-01~04-08). realtime recipe를 쓰는 프로젝트만 해당. 레시피 번들 예산은 40,900 bytes로 올렸다 | `src/adapters/realtime/`, `config/recipes/frontend-capability-recipes.json` | `bcad7b0`, `02d3fdf`, `7e37660`, `2c5e268` 외 | +| [계약] | browser-files 포트: 같은 턴의 abort는 `ABORTED`, 닫은 선택 창은 `DISMISSED`, 소진된 object URL lease는 재시도 가능으로 보고한다. Cache Storage는 후보 항목을 검증한 뒤에만 verified로 보고한다 (02-01~02-09). browser-files recipe를 쓰는 프로젝트만 해당 | `src/adapters/browser-file-storage/`, `src/adapters/cache-storage/` | `c9be8d6`, `d76653b`, `0b41cb3`, `55c0bf5` 외 | +| [계약] | 샘플 상세 경로가 `/examples/reference-resources/items/:resourceId`로 옮겨졌다. ID가 `new`·`status`인 항목도 상세가 열린다 (08-13) | `src/features/reference-feature/contracts/reference-feature-contract.ts`, `config/contracts/registry-change-evidence.json` | `d7b81c6` | +| [계약] | `tsconfig.base.json`에 `noUnusedLocals`를 켰다. 복사한 프로젝트의 쓰지 않는 import·변수가 `check:types`에서 실패한다 (12-12) | `tsconfig.base.json` | `49413af` | + +### 그 밖의 수정 + +- 부트: 앱 모듈 평가 실패, 분류되지 않은 오류, 재시도 가능한 실패에 오류 화면을 보여 준다 (09-03, 09-04, 09-10). `src/bootstrap/`, `src/presentation/boundaries/boot-error-shell.tsx` +- 부트: `FEATURE_OVERRIDES`의 모르는 키를 진단으로 남긴다 (09-09). `src/bootstrap/runtime-adapters.ts`, `scripts/check-release-admission.ts` +- 빌드: `dist` 파일을 다른 사용자도 읽을 수 있게 한다 (13-02). `scripts/lib/dist-permissions.ts` +- 공급망: 번들에 들어간 패키지 목록과 각 증거의 범위를 남긴다. 승격된 릴리스를 나중에 다시 검증한다 (13-12, 13-04). `scripts/lib/vite-module-inventory.ts`, `scripts/verify-exact-promotion-bundle.ts` +- 아키텍처 검사: dependency-cruiser 실행을 멈추고 import graph 하나로 검사한다. 경계 예외를 좁히고, 위반 메시지에 이유와 갈 곳을 적는다 (12-05~12-11). `scripts/check-architecture.ts` +- 기능 조립: `needs` 검사, 기능 두 개 설치 시 타입 유지, local-draft 샘플 정리 (09-01, 09-05, 09-06, 09-08, 09-12, 00-02). `src/features/`, `src/bootstrap/runtime-adapters.ts` +- 테스트 보강: production CSP 아래 빌드 smoke, 멱등 키 재사용, IndexedDB fake, KEYED 재시도 (13-08, 01-04, 05-08, 10-03) +- 샘플 제거: `test:sample-removal`이 다시 통과한다. 플랫폼 테스트가 샘플 대신 테스트 전용 기능을 쓴다 (14-01, 14-08, 00-01, 10-01). `scripts/test-sample-removal.ts`, `scripts/lib/removal-fixture.ts` +- 문서: README에 런타임 프로필·배포 변수·우선순위를 적고 `verify:documentation`이 변수 목록을 검사한다 (13-15). 성능 예산, 공급망, 운영 runbook 문서를 코드에 맞췄다 (13-13, 13-14, 03-06, 03-08). + +- 화면: 오류 종류마다 문구가 있고, 실패 화면에 지원 참조와 다음 행동이 나온다. 언어를 바꾸면 폼 오류도 다시 번역된다. 조회 실패의 인증·권한·없음 화면이 갤러리와 같은 컴포넌트다. 수정키 클릭은 브라우저에 맡긴다. 스크롤·해시 이동을 복원한다 (07-01, 08-02, 08-04, 08-07~08-12, F-10). `src/presentation/`, `src/presentation/i18n/` +- 접근성·visual 검사가 로그인 뒤 실제 화면을 상태별로 검사한다 (08-05, 11-02). `tests/e2e/accessibility.spec.ts` +- 계약 테스트: V2/V3 일치, 두 번째 기능의 레지스트리 통과, validator 결과 검사 (07-03, 07-05, 07-06, 09-07, F-3). `tests/unit/`, `src/contracts/` +- Service Worker: 알림 클릭, kill switch, drain 시간 초과, 이전 릴리스 fallback, 거절 클릭 경로, 시작 실패 텔레메트리 (06-01, 06-04, 06-05, 06-07~06-09). `src/adapters/web-push/`, `src/adapters/service-worker/`, `src/bootstrap/` +- 테스트 체계: 부하에 강한 대기, 커버리지 정책, 파일 하나 실행, 실제 타이머 복원, 포커스 테스트 금지, reference 데이터 E2E, 실제 모양 기능 규모 측정, SW 없는 구 탭 청크 복구, 성능 측정 중앙값, 모듈 평가 실패 부트 화면 (10-02, 10-04~10-07, 11-04~11-08, F-2). `tests/`, `scripts/scale/`, `scripts/lib/lab-performance.ts` +- 테스트 fixture가 공유 `node_modules`를 다시 쓰지 않고, 임시 폴더를 지운다 (F-4, F-12, 00-03). `scripts/lib/removal-fixture.ts`, `tests/unit/` +- 문서: 손으로 적은 게이트 수와 LOC를 지우고 `verify:documentation`의 검사 범위를 적었다 (14-07) + +### 알려진 제한 + +- Playwright spec은 chromium·firefox·webkit에서 확인했다. WebKit에서만 난 실패 1건(구 탭 청크 복구 spec의 콘솔 문구 허용 목록)은 `b1a36ab`로 고쳤다. +- 사용자 몫(SPEC "범위 밖" U-1~U-5, F-11)은 이 버전에 들어 있지 않다. + +## 0.1.0 — `main` `4626b73` (2026-09-24) + +태그가 없는 `main`이고 `package.json` 버전은 `0.1.0`이다. 이 커밋보다 앞에서 복사한 프로젝트는 아래 보안 수정부터 확인한다. + +| 표시 | 변경 | 영향 경로 | 커밋 | +|---|---|---|---| +| [보안] | 자격증명 헤더 값은 제어 문자가 없는 ByteString만 받는다. 대소문자만 다른 헤더 이름은 거절한다 (R-3.4) | `src/adapters/http/http-contract-bridge.ts`, `src/adapters/auth/external-session-adapter.ts` | `5e62b7e` | +| [보안] | REST v2 COMMAND는 POST/PUT/PATCH/DELETE만 쓴다. GET으로 선언된 명령이 CSRF 보호 없이 나가던 문제다 (R-7.4) | `src/contracts/api-operations.ts` | `f26fd18` | +| [보안] | 텔레메트리 리댁션이 문자열 중간의 토큰, URL 비밀 파라미터, 이메일을 가린다 (R-9.3) | `src/platform/telemetry/redact-telemetry.ts` | `4e0745c` | diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..6c9a9ac2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,26 @@ +# CLAUDE.md + +## 리뷰 기준 (모든 리뷰에 적용) + +이 repo를 리뷰할 때는 전체 리뷰든 모듈·PR·diff 리뷰든 [`docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`](docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md)를 기준으로 한다. + +- 발견 사항은 가이드의 28개 관점 번호로 분류한다. 결함 하나는 항목 하나로 적고 관련 관점 번호를 모두 붙인다(0.3절). 같은 결함을 여러 번 세지 않는다. +- 성격(확인된 결함 / 구조적 위험 / 미검증 / 개선 제안), 심각도(Critical~Low), 우선순위(P0~P3), 통제 수준(M0~M4), 증거(E0~E4)를 따로 적는다(35절). 확인하지 못한 것은 M0가 아니라 `미확인`이다. +- 발견 사항은 36.3절 양식, 최종 요약은 36.5절 양식, 관점별 판정은 36.2절 표를 쓴다. +- README와 설계 문서는 주장이다. 근거는 현재 커밋의 코드·설정·실행 결과에서 찾는다(34.1절). 이전 리뷰의 실행 결과를 현재 증거로 재사용하지 않는다. +- 리뷰에서는 코드를 고치지 않는다. 고치는 작업은 리뷰 문서를 근거로 별도로 진행한다. + +### 이 repo의 리뷰 전제 + +- 이 repo는 템플릿(reference implementation)이다. repo 안에 소비자가 없는 코드와 빈 레지스트리는 다운스트림용 확장 지점이지 죽은 코드가 아니다. 다만 갈라진 중복 복사본은 문제로 본다. +- adapter 배럴(`src/adapters/*/index.ts`)이 공개 경계다. +- adapter끼리 import할 수 있는 예외는 `.dependency-cruiser.json`의 kernel 예외(`src/adapters/platform/` 폴더 전체, `browser-file-storage/result.ts`, `cross-context-invalidation/index.ts`)뿐이다. 새 파일 단위 예외를 제안하지 않는다. +- 실행 형태는 브라우저 SPA + 정적 호스팅 + Service Worker다. SSR은 없다. + +### 전체 리뷰 절차 + +1. 기준 커밋과 가이드 0.1절 전제 표를 먼저 고정한다. +2. 게이트를 직접 실행하고 결과를 기록한다: `check:architecture`, `check:types`, `lint`, `test:unit`, `test:component`, `test:integration`, `test:contract`, `test:runtime-schema`, `verify:documentation`, `check:adapter-inventory`, `check:ci`. +3. 영역별로 서브에이전트를 병렬로 띄운다. 영역 분할은 가장 최근 `docs/reviews/*-maturity-review/README.md`의 영역 표를 재사용한다. +4. 각 에이전트는 `docs/reviews/-maturity-review/NN-<영역>.md`에 결과를 쓴다. +5. 오케스트레이터는 High 이상 발견을 코드에서 직접 재확인한 뒤 같은 폴더의 `README.md`에 범위(36.1), 28개 관점 판정표(36.2), 최종 요약(36.5), 발견 색인을 쓴다. diff --git a/README.md b/README.md index 7ccb0636..b21660d1 100644 --- a/README.md +++ b/README.md @@ -21,8 +21,54 @@ corepack pnpm install --frozen-lockfile corepack pnpm dev ``` -Runtime-public settings live in `public/config.json` and are validated before -the product tree mounts. Client secrets are forbidden. +## Runtime configuration + +Runtime-public settings are validated against one schema before the product +tree mounts (`runtimeConfigV2ArtifactSchema` in +`src/contracts/release-artifacts.ts`). Client secrets are forbidden. + +The source of truth is `config/runtime/.json`, one file per +environment: `local`, `development`, `staging`, `production`. `corepack pnpm +build` writes `dist/config.json` from the selected profile +(`scripts/generate-runtime-config.ts`). `public/config.json` is only the local +profile for `corepack pnpm dev`; the build replaces it, so settings put there +never reach a deployment. Keep it equal to `config/runtime/local.json` plus +`BUILD_ID: local-build` and `RELEASE_ID: local-release`; +`tests/unit/deployment-admission.test.ts` fails when the two differ. + +Build and deploy variables, lowest precedence first: + +| Variable | Sets | Default | +| --- | --- | --- | +| `APP_PROFILE` | which `config/runtime/.json` is used | `local`; an empty value fails the build | +| `RUNTIME_API_BASE_URL` | `API_BASE_URL`, overriding the profile | the profile value | +| `RUNTIME_TELEMETRY_ENDPOINT` | `TELEMETRY_ENDPOINT`, overriding the profile | the profile value | +| `VITE_BUILD_ID` | `BUILD_ID` in the runtime config and the release manifest | `local-build` | +| `RELEASE_ID` | `RELEASE_ID` in the runtime config and the release manifest | `local-release` | +| `RELEASE_TARGET` | the environment FE-GATE-027 admits the build to; must equal `APP_PROFILE` | none; admission refuses without it | + +`verify:documentation` fails if this table stops naming a variable the build or +admission reads (`scripts/verify-documentation-readiness.ts`). + +Only the two `RUNTIME_*` values can differ from the reviewed profile. Anything +else changes by editing the profile file. Staging and production reject demo +auth and non-HTTPS endpoints. + +A production build and its admission check: + +```bash +APP_PROFILE=production \ +RUNTIME_API_BASE_URL=https://api.example.com/ \ +RUNTIME_TELEMETRY_ENDPOINT=https://telemetry.example.com/v1/events \ +VITE_BUILD_ID= RELEASE_ID= \ +corepack pnpm build +APP_PROFILE=production RELEASE_TARGET=production corepack pnpm check:release-admission +``` + +With `CI=true` the gate runner (`corepack pnpm ci:gate`) also requires +`VITE_COMMIT_SHA`, `SOURCE_DATE_EPOCH` and `CI_RUNNER_IMAGE` before it runs a +gate (`scripts/lib/build-environment.ts`, `scripts/run-ci-gate.ts`). The CI variable +list is in [`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md). ## Included starter experience @@ -45,6 +91,46 @@ owner described in The client route policy is user experience only; server authorization remains authoritative. +## Support scope + +Four tiers. The status words on the right are the ones the catalogs and +design documents use; the next table maps them. + +| Tier | What it covers | Status words | +| --- | --- | --- | +| Default | In the default build and covered by the merge gates: the application shell and example routes, the REST HTTP executor, TanStack Query server state, Local/Session Storage registries, cross-tab invalidation, runtime config profiles and the release manifest check, `AUTH_MODE=external` (`demo` only in local/development), the typed message catalog, and the removable reference feature. `dist/` is served by a static host ([`docs/architecture/static-delivery.md`](docs/architecture/static-delivery.md)) | `COMPOSED` | +| Optional (recipe) | Not installed. A project copies one of the recipes in `config/recipes/frontend-capability-recipes.json` and narrows it ([`docs/architecture/optional-adapter-recipes.md`](docs/architecture/optional-adapter-recipes.md)). `realtime`, `offline-indexeddb`, `service-worker-pwa` and `file-transfer` also ship a tested reference runtime that the default build leaves out | `RECIPE_AVAILABLE`, `NOT_INSTALLED`, `AVAILABLE_NOT_COMPOSED` | +| Experimental | Designed and decided, but the runtime is missing or unfinished; finish it before building on it. GraphQL, gRPC-Web, Connect-Web and Protobuf adapters, Range resumable download, IndexedDB query persistence, the local preview decode-safety probe. `src/features/local-draft-feature` is an architecture sample, not installed | `DESIGNED_NOT_IMPLEMENTED` | +| Not supported | Deliberately not selected, or browsers cannot guarantee it: SSR, app-managed background upload and download, directory selection, persistent file handles, product query persistence, exactly-once delivery between tabs | `NOT_SELECTED`, `PLATFORM_LIMITED` | + +The rows come from +[`docs/architecture/browser-data-capability-completion-ledger.md`](docs/architecture/browser-data-capability-completion-ledger.md), +[`docs/architecture/client-cache-and-storage.md`](docs/architecture/client-cache-and-storage.md) +and +[`docs/architecture/api-contract-schema-mapper-and-server-state.md`](docs/architecture/api-contract-schema-mapper-and-server-state.md). + +| Status word | Where it appears | Meaning | Tier | +| --- | --- | --- | --- | +| `COMPOSED` | capability ledger, design documents | wired into the default production path | Default | +| `INSTALLED` | a project's own recipe catalog (step 10 of the recipe procedure) | the project added the recipe | Default, for that project | +| `RECIPE_AVAILABLE` | recipe catalog `status` | a recipe exists to copy; nothing is installed | Optional | +| `NOT_INSTALLED` | recipe catalog `defaultStatus`; a `src/features//NOT_INSTALLED` marker file | not part of the build | Optional (recipe) or Experimental (feature) | +| `AVAILABLE_NOT_COMPOSED` | capability ledger; recipe `referenceRuntime.status` | code and tests exist; the default build leaves it out | Optional | +| `DESIGNED_NOT_IMPLEMENTED` | capability ledger, design documents | design approved, runtime missing | Experimental | +| `NOT_SELECTED` | capability ledger, design documents | deliberately not chosen | Not supported | +| `PLATFORM_LIMITED` | capability ledger | browsers cannot guarantee it; offered only behind a probe and a fallback, if at all | Not supported as a guarantee | + +Gate results (`PASS`, `PASS_SCOPED`, `UNVERIFIED`, `FAIL_UNVERIFIED`) are +verdicts on evidence, not support tiers. + +Browsers: the build targets Chrome and Edge 111, Firefox 128, and Safari and +iOS 16.4. That is the higher of Vite 8's default JavaScript target +(`baseline-widely-available`; `vite.config.ts` sets no `build.target`) and +the CSS targets of Tailwind CSS 4. There is no browserslist. The end-to-end +suite runs on the desktop Chromium, Firefox and WebKit builds that Playwright +1.62 pins, plus one Chromium phone-size smoke (`playwright.config.ts`). Older +versions inside the target range and real mobile browsers are not tested. + ## Architecture This repository is a **Frontend Application Foundation**: a starter/composition @@ -98,6 +184,30 @@ project-owned integrations. They are target designs and review findings; a capability is not treated as implemented until its branch acceptance criteria and executable gates pass. +## Documentation + +[`docs/README.md`](docs/README.md) sorts the documents into current contracts, +target designs and work history. + +### Files you can delete after copying + +These record how the template was built. Nothing in the build or the gates +reads them, except the one file noted below +(`tests/unit/deletable-history-documents.test.ts` checks this). + +| Path | Contents | +| --- | --- | +| `docs/superpowers/` | past plans and specs | +| `docs/reviews/` | reviews and the review guide. Keep `docs/reviews/adapters/INVENTORY.md`: `check:adapter-inventory` (FE-GATE-010) reads it | +| `SPEC.md`, `tasks/` | requirements and task list of the 2026-09-25 review fix round | +| `CLAUDE.md` | review instructions for the template repository itself; replace it with your own | + +The reference feature is not in this list: deleting its directory alone +leaves tests, policy entries and CI scripts behind that fail the gates. +`scripts/test-sample-removal.ts` removes it from a copy of +the repository and lists everything that has to go with it (its header comment +and `SAMPLE_EXTRAS`); do the same in your project and run the gates. + ## Verification Common local checks: @@ -123,6 +233,11 @@ corepack pnpm drill:runbooks corepack pnpm check:ci ``` +`drill:runbooks` stops at the first drill that is not `PASS`. Without provider +evidence every drill ends `UNVERIFIED` (exit 3), because a drill never reports +a check it could not run locally as `PASS`; see "Runbook jobs" in +[`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md). + `test:all` is the ordinary product-development loop and intentionally excludes host-level CI-runner assurance. Run `corepack pnpm test:system` only on the compatible Linux assurance host described in @@ -152,21 +267,25 @@ corepack pnpm exec playwright install --with-deps chromium firefox webkit Two gates intentionally need external evidence: -- `review:a11y-manual` needs a signed human keyboard/focus/screen-reader review - for all ten registered routes: `APP_HOME`, `EXAMPLES_PLATFORM`, +- `review:a11y-manual` (release gate FE-GATE-028) needs a signed human + keyboard/focus/screen-reader review for all ten registered routes: `APP_HOME`, `EXAMPLES_PLATFORM`, `EXAMPLES_UI`, `EXAMPLES_STATES`, `EXAMPLES_AUTH`, `NOT_FOUND`, `REFERENCE_RESOURCE_LIST`, `REFERENCE_RESOURCE_DETAIL`, `REFERENCE_RESOURCE_FORM` and `REFERENCE_RESOURCE_STATUS`. `verify:documentation` derives that list from the route registry and fails if - this paragraph falls behind it. + this paragraph falls behind it. The merge gate FE-GATE-009 runs only + `review:a11y-manual -- --format-only`, which checks that every route record + keeps the template's fields, reviewed or still pending. - `collect:web-vitals-evidence` stays `FAIL_UNVERIFIED` until a reviewed minimum eligible-sample threshold and 28 days of production data exist. -Live release verification additionally requires `HOSTING_BASE_URL`. +Live hosting verification (FE-GATE-019, production stage) requires +`HOSTING_BASE_URL` and a deployed promoted release; without it the result is +`UNVERIFIED`, not `PASS`. ## CI and evidence -The 27-gate registry is `config/ci/gates.json`; the Gitea workflow is +The gate registry is `config/ci/gates.json`; the Gitea workflow is `.gitea/workflows/quality-gates.yml`. It follows: ```text @@ -174,8 +293,61 @@ MERGE_READY -> RELEASE_READY -> PROD_PROMOTION_READY -> FIELD_SLO_READY ``` `DOCUMENTATION_READY` is independent. No gate is downgraded to a warning. + +The workflow runs on pull requests, pushes to `main` and `develop`, and `v*` +tags. The Git host of this repository may not have Actions enabled, so a pull +request can show no gate status at all; no status is not a pass. Until the +host runs the workflow and marks the merge gates as required checks, run the 13 +merge gates locally before merging (FE-GATE-008 and 009 need Playwright +browsers): + +```bash +for gate in 001 002 003 004 005 006 007 008 009 010 011 013 020; do + corepack pnpm ci:gate -- "FE-GATE-$gate" || break +done +``` Machine-readable evidence is written below `artifacts/`; generated evidence is ignored by Git while `.gitkeep` files preserve the taxonomy. Operational details are in `docs/operations/`, with incident procedures in `docs/runbooks/`. + +## Updating a copied project + +Template versions are Git tags `vX.Y.Z`. [`CHANGELOG.md`](CHANGELOG.md) lists +the changes between tags, marks security fixes **[보안]** and contract changes +**[계약]** (backend, deployment, CI or feature code must change too), and names +the affected paths. + +Record where you started. Right after copying, commit a one-line +`.template-origin` file at the root of your project with the template tag (or +commit) you copied and the date, for example `v0.2.0 2026-09-26`. + +Take a template fix with Git. `cherry-pick` works even when your repository +does not share the template's history, because it merges against the picked +commit's parent: + +```bash +git remote add template