feat: add diagnostics and telemetry runtime

# Conflicts:
#	package.json

.dependency-cruiser.cjs

@@ -20,15 +20,71 @@ module.exports = {
     {
       name: "presentation-does-not-know-adapters",
       severity: "error",
-      from: { path: "^src/presentation" },
+      from: { path: "^src/presentation/(?!adapters/query)" },
       to: { path: "^(src/(adapters|bootstrap)|@tanstack)" },
     },
+    {
+      name: "page-templates-own-layout-only",
+      severity: "error",
+      from: { path: "^src/presentation/templates" },
+      to: {
+        path: "^(src/(application|adapters|bootstrap)|src/presentation/adapters|@tanstack)",
+      },
+    },
+    {
+      name: "icon-vendor-is-facade-only",
+      severity: "error",
+      from: {
+        path: "^src",
+        pathNot:
+          "^src/presentation/design-system/icons/vendors/lucide\\.tsx$",
+      },
+      to: { path: "^lucide-react$" },
+    },
     {
       name: "adapters-do-not-know-presentation",
       severity: "error",
       from: { path: "^src/adapters" },
       to: { path: "^src/(presentation|bootstrap)" },
     },
+    {
+      name: "feature-domain-is-framework-neutral",
+      severity: "error",
+      from: { path: "^src/features/[^/]+/domain" },
+      to: {
+        path: "^(src/(application|presentation|adapters|bootstrap)|src/features/[^/]+/(application|adapters|presentation)|react|react-dom|@tanstack)",
+      },
+    },
+    {
+      name: "feature-application-does-not-know-runtime",
+      severity: "error",
+      from: { path: "^src/features/[^/]+/application" },
+      to: {
+        path: "^(src/(presentation|adapters|bootstrap)|src/features/[^/]+/(adapters|presentation)|react|react-dom|@tanstack)",
+      },
+    },
+    {
+      name: "feature-presentation-does-not-know-outbound-adapters",
+      severity: "error",
+      from: { path: "^src/features/[^/]+/presentation" },
+      to: {
+        path: "^(src/(adapters|bootstrap)|src/features/[^/]+/adapters|@tanstack)",
+      },
+    },
+    {
+      name: "feature-adapters-do-not-know-presentation",
+      severity: "error",
+      from: { path: "^src/features/[^/]+/adapters" },
+      to: {
+        path: "^(src/(presentation|bootstrap)|src/features/[^/]+/presentation)",
+      },
+    },
+    {
+      name: "concrete-adapters-compose-only-in-bootstrap",
+      severity: "error",
+      from: { path: "^src/(domain|application|presentation|contracts)" },
+      to: { path: "^src/adapters" },
+    },
     {
       name: "no-circular-dependencies",
       severity: "error",
@@ -45,5 +101,8 @@ module.exports = {
       exportsFields: ["exports"],
       conditionNames: ["import", "require", "node", "default"],
     },
+    tsConfig: {
+      fileName: "tsconfig.app.json",
+    },
   },
 };

.gitea/workflows/quality-gates.yml

@@ -0,0 +1,189 @@
+name: frontend-quality-gates
+
+on:
+  push:
+    branches: [develop]
+    tags: ["v*"]
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      stage:
+        description: Highest promotion tier to evaluate
+        required: true
+        default: merge
+        type: choice
+        options:
+          - merge
+          - release
+          - production
+          - field
+          - documentation
+
+env:
+  NODE_VERSION: "24"
+
+jobs:
+  merge_gate:
+    name: ${{ matrix.gate }} / ${{ matrix.name }}
+    if: ${{ gitea.event_name != 'workflow_dispatch' || inputs.stage != 'documentation' }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { gate: FE-GATE-001, name: manifest-lockfile, browser: false }
+          - { gate: FE-GATE-002, name: lint, browser: false }
+          - { gate: FE-GATE-003, name: typecheck, browser: false }
+          - { gate: FE-GATE-004, name: runtime-schema, browser: false }
+          - { gate: FE-GATE-005, name: unit, browser: false }
+          - { gate: FE-GATE-006, name: component, browser: false }
+          - { gate: FE-GATE-007, name: integration, browser: false }
+          - { gate: FE-GATE-008, name: e2e, browser: true }
+          - { gate: FE-GATE-009, name: accessibility, browser: true }
+          - { gate: FE-GATE-010, name: architecture, browser: false }
+          - { gate: FE-GATE-011, name: build, browser: false }
+          - { gate: FE-GATE-013, name: security, browser: false }
+          - { gate: FE-GATE-020, name: sample-removal, browser: false }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+      - name: Frozen install
+        run: |
+          corepack enable
+          corepack pnpm install --frozen-lockfile
+      - name: Install Playwright browsers
+        if: ${{ matrix.browser }}
+        run: corepack pnpm exec playwright install --with-deps chromium firefox webkit
+      - name: Run blocking gate
+        run: corepack pnpm ci:gate -- ${{ matrix.gate }}
+      - name: Upload gate evidence
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.gate }}-${{ gitea.run_id }}
+          path: artifacts/
+          if-no-files-found: warn
+
+  release_gate:
+    name: ${{ matrix.gate }} / ${{ matrix.name }}
+    needs: merge_gate
+    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
+    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-015, name: release-coherence, browser: false }
+          - { gate: FE-GATE-019, name: hosting-header, browser: false }
+          - { gate: FE-GATE-026, name: lab-performance, browser: true }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+      - name: Frozen install
+        run: |
+          corepack enable
+          corepack pnpm install --frozen-lockfile
+      - name: Install Playwright browsers
+        if: ${{ matrix.browser }}
+        run: corepack pnpm exec playwright install --with-deps chromium firefox webkit
+      - name: Run blocking gate
+        run: corepack pnpm ci:gate -- ${{ matrix.gate }}
+      - name: Upload gate evidence
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.gate }}-${{ gitea.run_id }}
+          path: artifacts/
+          if-no-files-found: warn
+
+  production_gate:
+    name: ${{ matrix.gate }} / ${{ matrix.name }}
+    needs: release_gate
+    if: ${{ gitea.event_name == 'workflow_dispatch' && (inputs.stage == 'production' || inputs.stage == 'field') }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { gate: FE-GATE-016, name: rollback-drill }
+          - { gate: FE-GATE-021, name: runbook-boot-config }
+          - { gate: FE-GATE-022, name: runbook-chunk-mismatch }
+          - { gate: FE-GATE-023, name: runbook-api-degradation }
+          - { gate: FE-GATE-024, name: runbook-telemetry }
+          - { gate: FE-GATE-025, name: runbook-release-rollback }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+      - name: Frozen install
+        run: |
+          corepack enable
+          corepack pnpm install --frozen-lockfile
+      - name: Run blocking gate
+        run: corepack pnpm ci:gate -- ${{ matrix.gate }}
+      - name: Upload gate evidence
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.gate }}-${{ gitea.run_id }}
+          path: artifacts/
+          if-no-files-found: warn
+
+  field_gate:
+    name: FE-GATE-018 / field-web-vitals
+    needs: production_gate
+    if: ${{ gitea.event_name == 'workflow_dispatch' && inputs.stage == 'field' }}
+    runs-on: ubuntu-latest
+    env:
+      FIELD_WEB_VITALS_INPUT: ${{ vars.FIELD_WEB_VITALS_INPUT }}
+      MIN_ELIGIBLE_SAMPLES: ${{ vars.MIN_ELIGIBLE_SAMPLES }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+      - name: Frozen install
+        run: |
+          corepack enable
+          corepack pnpm install --frozen-lockfile
+      - name: Run blocking gate
+        run: corepack pnpm ci:gate -- FE-GATE-018
+      - name: Upload gate evidence
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: FE-GATE-018-${{ gitea.run_id }}
+          path: artifacts/
+          if-no-files-found: warn
+
+  documentation_gate:
+    name: FE-GATE-017 / diagram-review
+    if: ${{ gitea.event_name == 'workflow_dispatch' && inputs.stage == 'documentation' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+      - name: Frozen install
+        run: |
+          corepack enable
+          corepack pnpm install --frozen-lockfile
+      - name: Run documentation gate
+        run: corepack pnpm ci:gate -- FE-GATE-017
+      - name: Upload gate evidence
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: FE-GATE-017-${{ gitea.run_id }}
+          path: artifacts/
+          if-no-files-found: warn

.gitignore

@@ -1,6 +1,7 @@
 node_modules/
 dist/
 .vite/
+.tmp/
 playwright-report/
 test-results/
 coverage/
@@ -8,4 +9,5 @@ artifacts/**/*.json
 artifacts/**/*.xml
 artifacts/**/*.txt
 artifacts/**/*.sarif
+artifacts/tests/e2e/
 !artifacts/**/.gitkeep

README.md

@@ -1,2 +1,138 @@
-# clean-architecture-frontend-template
+# Clean Architecture Frontend Template
 
+A React/Vite reference implementation where architecture boundaries,
+integration behavior, release coherence, accessibility, performance, and
+operations are executable contracts rather than conventions.
+
+## Start locally
+
+Requirements: Node 24.11 or newer and Corepack. The repository pins pnpm in
+`package.json`.
+
+```bash
+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.
+
+## Included starter experience
+
+The default build mounts a domain-neutral application shell with a header,
+responsive sidebar, route focus management, session integration status, and a
+persistent `system` / `light` / `dark` theme selector.
+
+| Route | Purpose |
+| --- | --- |
+| `/` | implementation readiness and starter links |
+| `/examples/ui` | buttons, fields, cards, alerts, badges, modal, and tokens |
+| `/examples/states` | loading, refresh, empty, error, auth, forbidden, and not-found states |
+| `/examples/auth` | reactive external-auth integration seam |
+| `/sample/resources` | protected, domain-neutral integration route |
+
+`AUTH_MODE=demo` is credential-free and accepted only in local/development
+environments. Deployments use `AUTH_MODE=external` and provide the opaque auth
+owner described in
+[`docs/architecture/starter-experience.md`](docs/architecture/starter-experience.md).
+The client route policy is user experience only; server authorization remains
+authoritative.
+
+## Architecture
+
+Dependencies point inward:
+
+```text
+presentation -> application -> domain
+adapters -----^
+bootstrap composes concrete adapters
+contracts own cross-cutting registries
+```
+
+See `docs/architecture/overview.md`, `docs/architecture/layers.md`, and
+`docs/architecture/starter-experience.md`. The removable sample slice is under
+`src/sample/contract-fixture`; product code is not allowed to import it. The
+visible starter routes do not depend on that fixture and continue to build
+after it is removed.
+
+### Platform capability review
+
+The starter shell is implemented, but the repository review also records the
+remaining work required before feature teams can use every declared contract
+through one end-to-end application path:
+
+- [platform capability review](docs/architecture/frontend-platform-capability-review.md)
+- [ports, adapters, and feature boundaries](docs/architecture/frontend-ports-adapters-and-boundaries.md)
+- [TypeScript, state ownership, and data flow](docs/architecture/typescript-state-and-data-flow.md)
+- [routing, page templates, and reusable patterns](docs/architecture/routing-pages-and-patterns.md)
+- [design-system platform](docs/styling/design-system-platform.md)
+- [frontend platform testing strategy](docs/testing/frontend-platform-testing-strategy.md)
+- [implementation roadmap](docs/architecture/frontend-platform-implementation-roadmap.md)
+
+These documents distinguish repository defaults from opt-in adapters and
+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.
+
+## Verification
+
+Common local checks:
+
+```bash
+corepack pnpm lint
+corepack pnpm check:types
+corepack pnpm check:types:app
+corepack pnpm check:types:node
+corepack pnpm check:types:test
+corepack pnpm check:architecture
+corepack pnpm test:all
+corepack pnpm test:e2e
+corepack pnpm test:a11y
+corepack pnpm build
+corepack pnpm check:bundle
+corepack pnpm test:performance
+corepack pnpm verify:compatibility
+corepack pnpm verify:release
+corepack pnpm check:registries
+corepack pnpm drill:runbooks
+corepack pnpm check:ci
+```
+
+`check:types`는 source, Node scripts/config와 tests를 분리된 TypeScript
+project로 모두 검사한다. type/architecture/security/registry의 invalid
+fixture는 `config/ci/gates.json`에서 “실패해야 통과”하는 negative gate로
+실행된다. 도구 호환성 결정은
+[VD-01](docs/architecture/decisions/VD-01-typescript-lint-tooling.md)에 기록돼
+있다.
+
+Install the pinned Playwright browser engines before the first cross-browser
+run:
+
+```bash
+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 six registered routes.
+- `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`.
+
+## CI and evidence
+
+The 26-gate registry is `config/ci/gates.json`; the Gitea workflow is
+`.gitea/workflows/quality-gates.yml`. It follows:
+
+```text
+MERGE_READY -> RELEASE_READY -> PROD_PROMOTION_READY -> FIELD_SLO_READY
+```
+
+`DOCUMENTATION_READY` is independent. No gate is downgraded to a warning.
+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/`.

artifacts/performance/.gitkeep

@@ -1 +0,0 @@
-

artifacts/quality/.gitkeep

@@ -1 +0,0 @@
-

artifacts/release/.gitkeep

@@ -1 +0,0 @@
-

artifacts/security/.gitkeep

@@ -1 +0,0 @@
-

artifacts/tests/a11y-manual/APP_HOME.md

@@ -0,0 +1,18 @@
+# APP_HOME accessibility review
+
+Status: pending-manual-review
+Route ID: APP_HOME
+Release ID:
+Reviewer:
+Reviewed at:
+Signature:
+Attestation: pending
+M1 Keyboard: pending
+M2 Visible focus: pending
+M3 Route focus: pending
+M4 Modal focus: not-applicable (no modal on this route)
+M5 Error association: not-applicable (no form error on this route)
+M6 Color signal: pending
+M7 Reduced motion: pending
+Screen reader: pending
+Notes: Automated axe, keyboard-focus, and reduced-motion evidence is available; human review pending.

artifacts/tests/a11y-manual/EXAMPLES_AUTH.md

@@ -0,0 +1,18 @@
+# EXAMPLES_AUTH accessibility review
+
+Status: pending-manual-review
+Route ID: EXAMPLES_AUTH
+Release ID:
+Reviewer:
+Reviewed at:
+Signature:
+Attestation: pending
+M1 Keyboard: pending
+M2 Visible focus: pending
+M3 Route focus: pending
+M4 Modal focus: not-applicable (no modal on this route)
+M5 Error association: not-applicable (no form error on this route)
+M6 Color signal: pending
+M7 Reduced motion: pending
+Screen reader: pending
+Notes: Review session state announcements and unavailable external-integration behavior.

artifacts/tests/a11y-manual/EXAMPLES_STATES.md

@@ -0,0 +1,18 @@
+# EXAMPLES_STATES accessibility review
+
+Status: pending-manual-review
+Route ID: EXAMPLES_STATES
+Release ID:
+Reviewer:
+Reviewed at:
+Signature:
+Attestation: pending
+M1 Keyboard: pending
+M2 Visible focus: pending
+M3 Route focus: pending
+M4 Modal focus: not-applicable (no modal on this route)
+M5 Error association: not-applicable (no form error on this route)
+M6 Color signal: pending
+M7 Reduced motion: pending
+Screen reader: pending
+Notes: Review loading, refresh, empty, error, authentication, forbidden, and not-found announcements.

artifacts/tests/a11y-manual/EXAMPLES_UI.md

@@ -0,0 +1,18 @@
+# EXAMPLES_UI accessibility review
+
+Status: pending-manual-review
+Route ID: EXAMPLES_UI
+Release ID:
+Reviewer:
+Reviewed at:
+Signature:
+Attestation: pending
+M1 Keyboard: pending
+M2 Visible focus: pending
+M3 Route focus: pending
+M4 Modal focus: pending
+M5 Error association: pending
+M6 Color signal: pending
+M7 Reduced motion: pending
+Screen reader: pending
+Notes: Review form primitives, Menu/Tabs keyboard behavior, Toast announcements, Tooltip supplemental copy, text-field error association and modal focus containment/restoration.

artifacts/tests/a11y-manual/NOT_FOUND.md

@@ -0,0 +1,18 @@
+# NOT_FOUND accessibility review
+
+Status: pending-manual-review
+Route ID: NOT_FOUND
+Release ID:
+Reviewer:
+Reviewed at:
+Signature:
+Attestation: pending
+M1 Keyboard: pending
+M2 Visible focus: pending
+M3 Route focus: pending
+M4 Modal focus: not-applicable (no modal on this route)
+M5 Error association: not-applicable (no form error on this route)
+M6 Color signal: pending
+M7 Reduced motion: pending
+Screen reader: pending
+Notes: Human review pending.

artifacts/tests/a11y-manual/REFERENCE_RESOURCE_DETAIL.md

@@ -0,0 +1,18 @@
+# REFERENCE_RESOURCE_DETAIL accessibility review
+
+Status: pending-manual-review
+Route ID: REFERENCE_RESOURCE_DETAIL
+Release ID:
+Reviewer:
+Reviewed at:
+Signature:
+Attestation: pending
+M1 Keyboard: pending
+M2 Visible focus: pending
+M3 Route focus: pending
+M4 Modal focus: not-applicable (no modal on this route)
+M5 Error association: not-applicable (no form error on this route)
+M6 Color signal: pending
+M7 Reduced motion: pending
+Screen reader: pending
+Notes: Human review pending.

artifacts/tests/a11y-manual/REFERENCE_RESOURCE_FORM.md

@@ -0,0 +1,18 @@
+# REFERENCE_RESOURCE_FORM accessibility review
+
+Status: pending-manual-review
+Route ID: REFERENCE_RESOURCE_FORM
+Release ID:
+Reviewer:
+Reviewed at:
+Signature:
+Attestation: pending
+M1 Keyboard: pending
+M2 Visible focus: pending
+M3 Route focus: pending
+M4 Modal focus: pending
+M5 Error association: pending
+M6 Color signal: pending
+M7 Reduced motion: pending
+Screen reader: pending
+Notes: Human review pending.

artifacts/tests/a11y-manual/REFERENCE_RESOURCE_LIST.md

@@ -0,0 +1,18 @@
+# REFERENCE_RESOURCE_LIST accessibility review
+
+Status: pending-manual-review
+Route ID: REFERENCE_RESOURCE_LIST
+Release ID:
+Reviewer:
+Reviewed at:
+Signature:
+Attestation: pending
+M1 Keyboard: pending
+M2 Visible focus: pending
+M3 Route focus: pending
+M4 Modal focus: not-applicable (no modal on this route)
+M5 Error association: not-applicable (no form error on this route)
+M6 Color signal: pending
+M7 Reduced motion: pending
+Screen reader: pending
+Notes: Human review pending.

artifacts/tests/a11y-manual/REFERENCE_RESOURCE_STATUS.md

@@ -0,0 +1,18 @@
+# REFERENCE_RESOURCE_STATUS accessibility review
+
+Status: pending-manual-review
+Route ID: REFERENCE_RESOURCE_STATUS
+Release ID:
+Reviewer:
+Reviewed at:
+Signature:
+Attestation: pending
+M1 Keyboard: pending
+M2 Visible focus: pending
+M3 Route focus: pending
+M4 Modal focus: not-applicable (no modal on this route)
+M5 Error association: not-applicable (no form error on this route)
+M6 Color signal: pending
+M7 Reduced motion: pending
+Screen reader: pending
+Notes: Human review pending.

config/ci/gates.json

@@ -0,0 +1,387 @@
+{
+  "schemaVersion": 1,
+  "providerAdapter": ".gitea/workflows/quality-gates.yml",
+  "stages": {
+    "merge": {
+      "readiness": "MERGE_READY",
+      "needs": null,
+      "gates": [
+        "FE-GATE-001",
+        "FE-GATE-002",
+        "FE-GATE-003",
+        "FE-GATE-004",
+        "FE-GATE-005",
+        "FE-GATE-006",
+        "FE-GATE-007",
+        "FE-GATE-008",
+        "FE-GATE-009",
+        "FE-GATE-010",
+        "FE-GATE-011",
+        "FE-GATE-013",
+        "FE-GATE-020"
+      ]
+    },
+    "release": {
+      "readiness": "RELEASE_READY",
+      "needs": "merge",
+      "gates": [
+        "FE-GATE-012",
+        "FE-GATE-014",
+        "FE-GATE-015",
+        "FE-GATE-019",
+        "FE-GATE-026"
+      ]
+    },
+    "production": {
+      "readiness": "PROD_PROMOTION_READY",
+      "needs": "release",
+      "gates": [
+        "FE-GATE-016",
+        "FE-GATE-021",
+        "FE-GATE-022",
+        "FE-GATE-023",
+        "FE-GATE-024",
+        "FE-GATE-025"
+      ]
+    },
+    "field": {
+      "readiness": "FIELD_SLO_READY",
+      "needs": "production",
+      "gates": ["FE-GATE-018"]
+    },
+    "documentation": {
+      "readiness": "DOCUMENTATION_READY",
+      "needs": null,
+      "gates": ["FE-GATE-017"]
+    }
+  },
+  "gates": {
+    "FE-GATE-001": {
+      "name": "manifest-lockfile",
+      "steps": [{ "script": "verify:lockfile", "expect": "pass" }],
+      "logPath": "artifacts/quality/install.txt",
+      "evidence": ["artifacts/quality/install.txt"],
+      "retentionClass": "merge-cycle"
+    },
+    "FE-GATE-002": {
+      "name": "lint",
+      "steps": [{ "script": "lint", "expect": "pass" }],
+      "logPath": "artifacts/quality/lint.txt",
+      "evidence": ["artifacts/quality/lint.txt"],
+      "retentionClass": "merge-cycle"
+    },
+    "FE-GATE-003": {
+      "name": "typecheck",
+      "steps": [
+        { "script": "check:types", "expect": "pass" },
+        { "script": "check:types:fixture", "expect": "fail" },
+        { "script": "check:types:fixture:ts-port", "expect": "fail" },
+        { "script": "check:types:fixture:ts-result", "expect": "fail" },
+        { "script": "check:types:fixture:application-output", "expect": "fail" },
+        { "script": "check:types:fixture:application-input", "expect": "fail" },
+        { "script": "check:types:fixture:async-overlay", "expect": "fail" },
+        { "script": "check:types:fixture:route-runtime", "expect": "fail" },
+        { "script": "check:types:fixture:page-action", "expect": "fail" },
+        { "script": "check:types:fixture:icon-button", "expect": "fail" },
+        { "script": "check:types:fixture:i18n-key", "expect": "fail" },
+        { "script": "check:types:fixture:i18n-params", "expect": "fail" },
+        { "script": "check:types:fixture:diagnostics", "expect": "fail" }
+      ],
+      "logPath": "artifacts/quality/check-types.txt",
+      "evidence": ["artifacts/quality/check-types.txt"],
+      "retentionClass": "merge-cycle"
+    },
+    "FE-GATE-004": {
+      "name": "runtime-schema",
+      "steps": [{ "script": "test:runtime-schema", "expect": "pass" }],
+      "logPath": "artifacts/quality/gates/FE-GATE-004.txt",
+      "evidence": ["artifacts/tests/runtime-schema.xml"],
+      "retentionClass": "merge-cycle"
+    },
+    "FE-GATE-005": {
+      "name": "unit",
+      "steps": [{ "script": "test:unit", "expect": "pass" }],
+      "logPath": "artifacts/quality/gates/FE-GATE-005.txt",
+      "evidence": ["artifacts/tests/unit.xml"],
+      "retentionClass": "merge-cycle"
+    },
+    "FE-GATE-006": {
+      "name": "component",
+      "steps": [{ "script": "test:component", "expect": "pass" }],
+      "logPath": "artifacts/quality/gates/FE-GATE-006.txt",
+      "evidence": ["artifacts/tests/component.xml"],
+      "retentionClass": "merge-cycle"
+    },
+    "FE-GATE-007": {
+      "name": "integration",
+      "steps": [
+        { "script": "test:integration", "expect": "pass" },
+        { "script": "test:reference-feature", "expect": "pass" }
+      ],
+      "logPath": "artifacts/quality/gates/FE-GATE-007.txt",
+      "evidence": [
+        "artifacts/tests/integration.xml",
+        "artifacts/tests/reference-feature.xml"
+      ],
+      "retentionClass": "merge-cycle"
+    },
+    "FE-GATE-008": {
+      "name": "e2e",
+      "steps": [{ "script": "test:e2e", "expect": "pass" }],
+      "logPath": "artifacts/quality/gates/FE-GATE-008.txt",
+      "evidence": ["artifacts/tests/e2e/report/index.html"],
+      "retentionClass": "merge-cycle"
+    },
+    "FE-GATE-009": {
+      "name": "accessibility",
+      "steps": [
+        { "script": "test:a11y", "expect": "pass" },
+        { "script": "review:a11y-manual", "expect": "pass" }
+      ],
+      "logPath": "artifacts/quality/gates/FE-GATE-009.txt",
+      "evidence": [
+        "artifacts/tests/a11y.json",
+        "artifacts/tests/a11y-manual/APP_HOME.md",
+        "artifacts/tests/a11y-manual/EXAMPLES_UI.md",
+        "artifacts/tests/a11y-manual/EXAMPLES_STATES.md",
+        "artifacts/tests/a11y-manual/EXAMPLES_AUTH.md",
+        "artifacts/tests/a11y-manual/REFERENCE_RESOURCE_LIST.md",
+        "artifacts/tests/a11y-manual/NOT_FOUND.md",
+        "artifacts/tests/a11y-manual/report.json"
+      ],
+      "retentionClass": "merge-cycle"
+    },
+    "FE-GATE-010": {
+      "name": "architecture",
+      "steps": [
+        { "script": "check:architecture", "expect": "pass" },
+        { "script": "check:design-system", "expect": "pass" },
+        { "script": "check:design-system:fixture", "expect": "fail" },
+        { "script": "check:i18n", "expect": "pass" },
+        { "script": "check:i18n:fixture", "expect": "fail" },
+        { "script": "check:diagnostics", "expect": "pass" },
+        { "script": "check:diagnostics:fixture", "expect": "fail" },
+        { "script": "check:registries", "expect": "pass" },
+        { "script": "check:registries:fixture", "expect": "fail" },
+        { "script": "check:routes:fixture", "expect": "fail" }
+      ],
+      "logPath": "artifacts/quality/gates/FE-GATE-010.txt",
+      "evidence": [
+        "artifacts/quality/dependency-report.json",
+        "artifacts/quality/design-system.json",
+        "artifacts/quality/design-system-fixture.json",
+        "artifacts/quality/i18n.json",
+        "artifacts/quality/i18n-fixture.json",
+        "artifacts/quality/diagnostics.json",
+        "artifacts/quality/diagnostics-fixture.json",
+        "artifacts/quality/registries.json",
+        "artifacts/quality/registry-fixture.json",
+        "artifacts/quality/route-registry-fixture.json"
+      ],
+      "retentionClass": "merge-cycle"
+    },
+    "FE-GATE-011": {
+      "name": "build",
+      "steps": [{ "script": "build", "expect": "pass" }],
+      "logPath": "artifacts/quality/gates/FE-GATE-011.txt",
+      "evidence": [
+        "artifacts/release/build-manifest.json",
+        "artifacts/release/runtime-config.schema.json"
+      ],
+      "retentionClass": "release-coherence"
+    },
+    "FE-GATE-012": {
+      "name": "bundle",
+      "steps": [
+        { "script": "build", "expect": "pass" },
+        { "script": "check:bundle", "expect": "pass" }
+      ],
+      "logPath": "artifacts/quality/gates/FE-GATE-012.txt",
+      "evidence": ["artifacts/performance/bundle.json"],
+      "retentionClass": "release-coherence"
+    },
+    "FE-GATE-013": {
+      "name": "security",
+      "steps": [
+        { "script": "build:release", "expect": "pass" },
+        { "script": "check:browser-security", "expect": "pass" }
+      ],
+      "logPath": "artifacts/quality/gates/FE-GATE-013.txt",
+      "evidence": [
+        "artifacts/security/scan.sarif",
+        "artifacts/release/dependency-inventory.json",
+        "artifacts/security/dependency-diff.json"
+      ],
+      "retentionClass": "release-coherence"
+    },
+    "FE-GATE-014": {
+      "name": "config-compatibility",
+      "steps": [{ "script": "verify:compatibility", "expect": "pass" }],
+      "logPath": "artifacts/quality/gates/FE-GATE-014.txt",
+      "evidence": ["artifacts/release/compatibility.json"],
+      "retentionClass": "release-coherence"
+    },
+    "FE-GATE-015": {
+      "name": "release-coherence",
+      "steps": [
+        { "script": "build", "expect": "pass" },
+        { "script": "verify:release", "expect": "pass" }
+      ],
+      "logPath": "artifacts/quality/gates/FE-GATE-015.txt",
+      "evidence": ["artifacts/release/verification.json"],
+      "retentionClass": "release-coherence"
+    },
+    "FE-GATE-016": {
+      "name": "rollback-drill",
+      "steps": [
+        { "script": "build", "expect": "pass" },
+        {
+          "script": "drill:runbook",
+          "args": ["--", "FE-RB-005"],
+          "expect": "pass"
+        }
+      ],
+      "logPath": "artifacts/quality/gates/FE-GATE-016.txt",
+      "evidence": [
+        "artifacts/runbooks/FE-RB-005/local-release/record.json"
+      ],
+      "retentionClass": "prod-drill"
+    },
+    "FE-GATE-017": {
+      "name": "diagram-review",
+      "steps": [{ "script": "verify:documentation", "expect": "pass" }],
+      "logPath": "artifacts/quality/gates/FE-GATE-017.txt",
+      "evidence": ["artifacts/quality/documentation-review.json"],
+      "retentionClass": "documentation"
+    },
+    "FE-GATE-018": {
+      "name": "field-web-vitals",
+      "requiresEnvironment": [
+        "FIELD_WEB_VITALS_INPUT",
+        "MIN_ELIGIBLE_SAMPLES"
+      ],
+      "steps": [
+        { "script": "collect:web-vitals-evidence", "expect": "pass" }
+      ],
+      "logPath": "artifacts/quality/gates/FE-GATE-018.txt",
+      "evidence": ["artifacts/performance/field-web-vitals.json"],
+      "retentionClass": "field"
+    },
+    "FE-GATE-019": {
+      "name": "hosting-header",
+      "requiresEnvironment": ["HOSTING_BASE_URL"],
+      "steps": [
+        { "script": "build", "expect": "pass" },
+        { "script": "verify:hosting-headers", "expect": "pass" }
+      ],
+      "logPath": "artifacts/quality/gates/FE-GATE-019.txt",
+      "evidence": ["artifacts/release/hosting-headers.json"],
+      "retentionClass": "release-coherence"
+    },
+    "FE-GATE-020": {
+      "name": "reference-feature-removal",
+      "steps": [{ "script": "test:sample-removal", "expect": "pass" }],
+      "logPath": "artifacts/quality/gates/FE-GATE-020.txt",
+      "evidence": ["artifacts/tests/sample-removal.xml"],
+      "retentionClass": "merge-cycle"
+    },
+    "FE-GATE-021": {
+      "name": "runbook-boot-config",
+      "steps": [
+        { "script": "build", "expect": "pass" },
+        {
+          "script": "drill:runbook",
+          "args": ["--", "FE-RB-001"],
+          "expect": "pass"
+        }
+      ],
+      "logPath": "artifacts/quality/gates/FE-GATE-021.txt",
+      "evidence": [
+        "artifacts/runbooks/FE-RB-001/local-release/record.json"
+      ],
+      "retentionClass": "prod-drill"
+    },
+    "FE-GATE-022": {
+      "name": "runbook-chunk-mismatch",
+      "steps": [
+        { "script": "build", "expect": "pass" },
+        {
+          "script": "drill:runbook",
+          "args": ["--", "FE-RB-002"],
+          "expect": "pass"
+        }
+      ],
+      "logPath": "artifacts/quality/gates/FE-GATE-022.txt",
+      "evidence": [
+        "artifacts/runbooks/FE-RB-002/local-release/record.json"
+      ],
+      "retentionClass": "prod-drill"
+    },
+    "FE-GATE-023": {
+      "name": "runbook-api-degradation",
+      "steps": [
+        { "script": "build", "expect": "pass" },
+        {
+          "script": "drill:runbook",
+          "args": ["--", "FE-RB-003"],
+          "expect": "pass"
+        }
+      ],
+      "logPath": "artifacts/quality/gates/FE-GATE-023.txt",
+      "evidence": [
+        "artifacts/runbooks/FE-RB-003/local-release/record.json"
+      ],
+      "retentionClass": "prod-drill"
+    },
+    "FE-GATE-024": {
+      "name": "runbook-telemetry",
+      "steps": [
+        { "script": "build", "expect": "pass" },
+        {
+          "script": "drill:runbook",
+          "args": ["--", "FE-RB-004"],
+          "expect": "pass"
+        }
+      ],
+      "logPath": "artifacts/quality/gates/FE-GATE-024.txt",
+      "evidence": [
+        "artifacts/runbooks/FE-RB-004/local-release/record.json"
+      ],
+      "retentionClass": "prod-drill"
+    },
+    "FE-GATE-025": {
+      "name": "runbook-release-rollback",
+      "steps": [
+        { "script": "build", "expect": "pass" },
+        {
+          "script": "drill:runbook",
+          "args": ["--", "FE-RB-005"],
+          "expect": "pass"
+        }
+      ],
+      "logPath": "artifacts/quality/gates/FE-GATE-025.txt",
+      "evidence": [
+        "artifacts/runbooks/FE-RB-005/local-release/record.json"
+      ],
+      "retentionClass": "prod-drill"
+    },
+    "FE-GATE-026": {
+      "name": "lab-performance",
+      "steps": [
+        { "script": "build", "expect": "pass" },
+        { "script": "test:performance", "expect": "pass" }
+      ],
+      "logPath": "artifacts/quality/gates/FE-GATE-026.txt",
+      "evidence": ["artifacts/performance/lab.json"],
+      "retentionClass": "release-coherence"
+    }
+  },
+  "retention": {
+    "durationStatus": "UNSUPPORTED_PENDING_ORGANIZATION_POLICY",
+    "merge-cycle": "at least through pull-request readiness decision",
+    "release-coherence": "at least until the next release is promoted",
+    "prod-drill": "at least until the next production promotion decision",
+    "field": "through the 28-day window and aggregation",
+    "documentation": "through documentation readiness review"
+  }
+}

config/compatibility/fixtures.json

@@ -0,0 +1,63 @@
+{
+  "schemaVersion": 1,
+  "families": {
+    "api": {
+      "additive": {
+        "before": { "required": ["id"], "properties": { "id": {} } },
+        "after": {
+          "required": ["id"],
+          "properties": { "id": {}, "displayName": {} }
+        }
+      },
+      "breaking": {
+        "before": { "required": ["id"], "properties": { "id": {} } },
+        "after": {
+          "required": ["id", "name"],
+          "properties": { "id": {}, "name": {} }
+        }
+      }
+    },
+    "config": {
+      "additive": {
+        "before": { "required": ["APP_ENV"], "properties": { "APP_ENV": {} } },
+        "after": {
+          "required": ["APP_ENV"],
+          "properties": { "APP_ENV": {}, "OPTIONAL_FLAG": {} }
+        }
+      },
+      "breaking": {
+        "before": { "required": ["APP_ENV"], "properties": { "APP_ENV": {} } },
+        "after": {
+          "required": ["APP_ENV", "NEW_REQUIRED"],
+          "properties": { "APP_ENV": {}, "NEW_REQUIRED": {} }
+        }
+      }
+    },
+    "storage": {
+      "additive": {
+        "before": { "properties": { "theme": {} } },
+        "after": { "properties": { "theme": {}, "contrast": {} } }
+      },
+      "breaking": {
+        "before": { "properties": { "theme": {} } },
+        "after": { "properties": {} }
+      }
+    },
+    "release": {
+      "additive": {
+        "before": { "required": ["buildId"], "properties": { "buildId": {} } },
+        "after": {
+          "required": ["buildId"],
+          "properties": { "buildId": {}, "builtAt": {} }
+        }
+      },
+      "breaking": {
+        "before": { "required": ["buildId"], "properties": { "buildId": {} } },
+        "after": {
+          "required": ["buildId", "assetManifestHash"],
+          "properties": { "buildId": {}, "assetManifestHash": {} }
+        }
+      }
+    }
+  }
+}

config/contracts/registry-governance.json

@@ -0,0 +1,190 @@
+{
+  "schemaVersion": 1,
+  "registries": [
+    {
+      "registryId": "FE-REG-ROUTE",
+      "path": "src/features/installed-feature-contracts.js",
+      "exportName": "ROUTE_REGISTRY",
+      "owner": "feature-routing-navigation-guard-contract",
+      "uniqueFields": ["routeId", "path", "chunkId"],
+      "allowedValues": {
+        "paramsSchema": [null, "NotFoundSplat", "ReferenceResourceParams"],
+        "searchSchema": [null, "ReferenceResourceListQuery"],
+        "loadingSurface": [
+          "app-shell",
+          "example-page",
+          "reference-resource-list",
+          "reference-resource-detail",
+          "reference-resource-form",
+          "reference-resource-status",
+          "none"
+        ],
+        "errorSurface": [
+          "route-boundary",
+          "feature-boundary",
+          "not-found"
+        ],
+        "chunkId": [
+          "route-home",
+          "route-examples-ui",
+          "route-examples-states",
+          "route-examples-auth",
+          "route-reference-resources",
+          "route-reference-resource-detail",
+          "route-reference-resource-form",
+          "route-reference-resource-status",
+          "route-not-found"
+        ]
+      },
+      "references": [
+        {
+          "field": "routeId",
+          "registryId": "FE-REG-ROUTE-RUNTIME",
+          "targetField": "routeId"
+        }
+      ],
+      "requiredFields": [
+        "routeId",
+        "path",
+        "paramsSchema",
+        "searchSchema",
+        "access",
+        "loadingSurface",
+        "errorSurface",
+        "chunkId"
+      ]
+    },
+    {
+      "registryId": "FE-REG-ROUTE-RUNTIME",
+      "path": "src/features/installed-feature-contracts.js",
+      "exportName": "ROUTE_RUNTIME_CONTRACT",
+      "owner": "feature-frontend-routing-release-recovery-runtime",
+      "requiredFields": [
+        "routeId",
+        "moduleId",
+        "paramsCodec",
+        "searchCodec"
+      ],
+      "uniqueFields": ["routeId", "moduleId"],
+      "allowedValues": {
+        "moduleId": [
+          "home-page",
+          "ui-gallery-page",
+          "state-gallery-page",
+          "auth-example-page",
+          "reference-resource-page",
+          "reference-resource-detail-page",
+          "reference-resource-form-page",
+          "reference-resource-status-page",
+          "not-found-page"
+        ],
+        "paramsCodec": ["none", "NotFoundSplat", "ReferenceResourceParams"],
+        "searchCodec": ["none", "ReferenceResourceListQuery"]
+      },
+      "references": [
+        {
+          "field": "routeId",
+          "registryId": "FE-REG-ROUTE",
+          "targetField": "routeId"
+        }
+      ]
+    },
+    {
+      "registryId": "FE-REG-API",
+      "path": "src/features/installed-feature-contracts.js",
+      "exportName": "API_OPERATIONS",
+      "owner": "feature-api-client-response-envelope-contract",
+      "requiredFields": [
+        "method",
+        "path",
+        "operationId",
+        "auth",
+        "timeoutMs",
+        "idempotency",
+        "retry",
+        "requestSource",
+        "requestSchema",
+        "responseSchema",
+        "owner"
+      ]
+    },
+    {
+      "registryId": "FE-REG-ENV",
+      "path": "src/contracts/env.js",
+      "exportName": "ENV_REGISTRY",
+      "owner": "feature-frontend-env-runtime-config-contract",
+      "requiredFields": ["phase", "classification", "required", "defaultValue"]
+    },
+    {
+      "registryId": "FE-REG-STORAGE",
+      "path": "src/contracts/storage-keys.js",
+      "exportName": "STORAGE_REGISTRY",
+      "owner": "feature-frontend-storage-registry-contract",
+      "requiredFields": [
+        "logicalName",
+        "physicalKey",
+        "backend",
+        "classification",
+        "schemaVersion",
+        "ttl",
+        "migration",
+        "quotaFallback"
+      ]
+    },
+    {
+      "registryId": "FE-REG-ERROR",
+      "path": "src/contracts/errors.js",
+      "exportName": "ERROR_REGISTRY",
+      "owner": "feature-frontend-error-classification-boundary-contract",
+      "requiredFields": [
+        "kind",
+        "defaultRetryable",
+        "severity",
+        "userMessageKey",
+        "action",
+        "telemetryEvent",
+        "redaction"
+      ]
+    },
+    {
+      "registryId": "FE-REG-QUERY",
+      "path": "src/features/installed-feature-contracts.js",
+      "exportName": "QUERY_REGISTRY",
+      "owner": "feature-server-state-caching-contract",
+      "requiredFields": [
+        "namespace",
+        "serialization",
+        "identity",
+        "invalidation",
+        "version",
+        "persistence"
+      ]
+    },
+    {
+      "registryId": "FE-REG-TELEMETRY",
+      "path": "src/contracts/telemetry.js",
+      "exportName": "TELEMETRY_REGISTRY",
+      "owner": "feature-frontend-observability-logging-trace-contract",
+      "requiredFields": [
+        "eventName",
+        "trigger",
+        "requiredAttributes",
+        "optionalAttributes",
+        "forbiddenAttributes",
+        "sampling",
+        "delivery"
+      ]
+    },
+    {
+      "registryId": "FE-REG-RELEASE",
+      "path": "src/contracts/release-tokens.js",
+      "exportName": "RELEASE_TOKEN_REGISTRY",
+      "owner": "feature-frontend-release-cache-rollback-contract",
+      "requiredFields": ["token", "source", "compatibilityRole"]
+    }
+  ],
+  "compatibilityImpact": {
+    "allowed": ["none", "additive", "behavior-change", "breaking"],
+    "current": "behavior-change"
+  }
+}

config/hosting/cache-policy.json

@@ -0,0 +1,35 @@
+{
+  "schemaVersion": 1,
+  "surfaces": {
+    "index": {
+      "path": "/",
+      "cacheControl": "no-cache",
+      "contentTypes": ["text/html"],
+      "securityHeaders": true
+    },
+    "runtimeConfig": {
+      "path": "/config.json",
+      "cacheControl": "no-store",
+      "contentTypes": ["application/json"],
+      "securityHeaders": true
+    },
+    "releaseManifest": {
+      "path": "/release-manifest.json",
+      "cacheControl": "no-store",
+      "contentTypes": ["application/json"],
+      "securityHeaders": true
+    },
+    "hashedAsset": {
+      "pathPattern": "/assets/*",
+      "cacheControl": "public, max-age=31536000, immutable",
+      "contentTypes": ["text/javascript", "application/javascript"],
+      "securityHeaders": false
+    },
+    "sourceMap": {
+      "public": false
+    },
+    "serviceWorker": {
+      "enabled": false
+    }
+  }
+}

config/hosting/response-headers.fixture.json

@@ -0,0 +1,39 @@
+{
+  "schemaVersion": 1,
+  "responses": {
+    "index": {
+      "cache-control": "no-cache",
+      "content-type": "text/html; charset=utf-8",
+      "content-security-policy": "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; form-action 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self' https:; font-src 'self'; upgrade-insecure-requests",
+      "strict-transport-security": "max-age=31536000; includeSubDomains",
+      "x-frame-options": "DENY",
+      "referrer-policy": "strict-origin-when-cross-origin",
+      "x-content-type-options": "nosniff",
+      "permissions-policy": "camera=(), microphone=(), geolocation=()"
+    },
+    "runtimeConfig": {
+      "cache-control": "no-store",
+      "content-type": "application/json; charset=utf-8",
+      "content-security-policy": "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; form-action 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self' https:; font-src 'self'; upgrade-insecure-requests",
+      "strict-transport-security": "max-age=31536000; includeSubDomains",
+      "x-frame-options": "DENY",
+      "referrer-policy": "strict-origin-when-cross-origin",
+      "x-content-type-options": "nosniff",
+      "permissions-policy": "camera=(), microphone=(), geolocation=()"
+    },
+    "releaseManifest": {
+      "cache-control": "no-store",
+      "content-type": "application/json; charset=utf-8",
+      "content-security-policy": "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; form-action 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self' https:; font-src 'self'; upgrade-insecure-requests",
+      "strict-transport-security": "max-age=31536000; includeSubDomains",
+      "x-frame-options": "DENY",
+      "referrer-policy": "strict-origin-when-cross-origin",
+      "x-content-type-options": "nosniff",
+      "permissions-policy": "camera=(), microphone=(), geolocation=()"
+    },
+    "hashedAsset": {
+      "cache-control": "public, max-age=31536000, immutable",
+      "content-type": "text/javascript; charset=utf-8"
+    }
+  }
+}

config/hosting/security-headers.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "headers": {
+    "Content-Security-Policy": "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; form-action 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self' https:; font-src 'self'; upgrade-insecure-requests",
+    "Strict-Transport-Security": "max-age=31536000; includeSubDomains",
+    "X-Frame-Options": "DENY",
+    "Referrer-Policy": "strict-origin-when-cross-origin",
+    "X-Content-Type-Options": "nosniff",
+    "Permissions-Policy": "camera=(), microphone=(), geolocation=()"
+  }
+}

config/performance/budgets.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": 1,
+  "bundle": {
+    "initialJsGzipBytes": 204800,
+    "lazyChunkGzipBytes": 122880
+  },
+  "lab": {
+    "lcpMs": 2500,
+    "cls": 0.1,
+    "namedInteractionMs": 200
+  },
+  "field": {
+    "p75LcpMs": 2500,
+    "p75Cls": 0.1,
+    "p75InpMs": 200,
+    "minimumEligibleSamples": null
+  }
+}

config/performance/field-input.example.json

@@ -0,0 +1,25 @@
+{
+  "schemaVersion": 1,
+  "releaseId": "local-release",
+  "environment": "replace-with-production",
+  "source": {
+    "system": "",
+    "exportId": ""
+  },
+  "privacy": {
+    "approved": false,
+    "approvalRef": ""
+  },
+  "window": {
+    "start": "2026-06-01T00:00:00Z",
+    "end": "2026-06-29T00:00:00Z"
+  },
+  "thresholdDecision": {
+    "status": "pending",
+    "minimumEligibleSamples": null,
+    "owner": "",
+    "reviewedAt": "",
+    "evidenceRef": ""
+  },
+  "samples": []
+}

config/release/coherence-fixtures.json

@@ -0,0 +1,77 @@
+{
+  "schemaVersion": 1,
+  "fixtures": [
+    {
+      "name": "coherent-release",
+      "expectedCompatible": true,
+      "frontend": {
+        "buildId": "build-a",
+        "configSchemaVersion": "1.0",
+        "apiContractVersion": "1.0",
+        "assetManifestHash": "assets-a",
+        "releaseId": "release-a"
+      },
+      "runtime": {
+        "buildId": "build-a",
+        "configSchemaVersion": "1.1",
+        "apiContractVersion": "1.2",
+        "assetManifestHash": "assets-a",
+        "releaseId": "release-a"
+      }
+    },
+    {
+      "name": "mixed-html-and-assets",
+      "expectedCompatible": false,
+      "frontend": {
+        "buildId": "build-a",
+        "configSchemaVersion": "1.0",
+        "apiContractVersion": "1.0",
+        "assetManifestHash": "assets-a",
+        "releaseId": "release-a"
+      },
+      "runtime": {
+        "buildId": "build-b",
+        "configSchemaVersion": "1.0",
+        "apiContractVersion": "1.0",
+        "assetManifestHash": "assets-b",
+        "releaseId": "release-b"
+      }
+    },
+    {
+      "name": "incompatible-runtime-config",
+      "expectedCompatible": false,
+      "frontend": {
+        "buildId": "build-a",
+        "configSchemaVersion": "1.0",
+        "apiContractVersion": "1.0",
+        "assetManifestHash": "assets-a",
+        "releaseId": "release-a"
+      },
+      "runtime": {
+        "buildId": "build-a",
+        "configSchemaVersion": "2.0",
+        "apiContractVersion": "1.0",
+        "assetManifestHash": "assets-a",
+        "releaseId": "release-a"
+      }
+    },
+    {
+      "name": "incompatible-api-contract",
+      "expectedCompatible": false,
+      "frontend": {
+        "buildId": "build-a",
+        "configSchemaVersion": "1.0",
+        "apiContractVersion": "1.0",
+        "assetManifestHash": "assets-a",
+        "releaseId": "release-a"
+      },
+      "runtime": {
+        "buildId": "build-a",
+        "configSchemaVersion": "1.0",
+        "apiContractVersion": "2.0",
+        "assetManifestHash": "assets-a",
+        "releaseId": "release-a"
+      }
+    }
+  ]
+}

config/runbooks/runbooks.json

@@ -0,0 +1,93 @@
+{
+  "schemaVersion": 1,
+  "runbooks": {
+    "FE-RB-001": {
+      "title": "Boot configuration failure",
+      "gateId": "FE-GATE-021",
+      "triggerKinds": ["BOOT_CONFIG_FAILURE"],
+      "containment": "stop product route mount, show the safe support shell, and refetch at most once",
+      "window": "owner triage planned-default 5m",
+      "escalation": ["env-config owner", "release owner"],
+      "recoveryEvidence": [
+        "clean-session boot",
+        "product root mount",
+        "config validation",
+        "no repeated boot error"
+      ],
+      "negativeFixture": "a valid config followed by an injected mount failure must fail recovery"
+    },
+    "FE-RB-002": {
+      "title": "Chunk, manifest, or deployment mismatch",
+      "gateId": "FE-GATE-022",
+      "triggerKinds": [
+        "CHUNK_LOAD_FAILURE",
+        "RELEASE_MANIFEST_FAILURE",
+        "DEPLOY_MISMATCH"
+      ],
+      "containment": "warn for dirty state, fetch manifest no-store once, and allow one guarded reload",
+      "window": "release owner triage planned-default 5m",
+      "escalation": ["release-cache owner", "hosting/CDN owner"],
+      "recoveryEvidence": [
+        "entry and lazy assets reachable",
+        "release tuple coherent",
+        "second reload blocked",
+        "critical route smoke"
+      ],
+      "negativeFixture": "a second failure for the same release pair must not reload"
+    },
+    "FE-RB-003": {
+      "title": "Backend API degradation",
+      "gateId": "FE-GATE-023",
+      "triggerKinds": [
+        "TERMINAL_NETWORK_RATE",
+        "REQUEST_TIMEOUT_RATE",
+        "SERVER_FAILURE_RATE",
+        "SCHEMA_MISMATCH"
+      ],
+      "containment": "do not expand retry caps, serve safe stale reads, and never retry an unkeyed mutation",
+      "window": "rolling 5m trigger; first classification planned-default 10m",
+      "escalation": [
+        "api-client owner",
+        "backend operation owner",
+        "release compatibility owner"
+      ],
+      "recoveryEvidence": [
+        "terminal failure rate at baseline",
+        "no retry amplification",
+        "critical read/write smoke",
+        "schema fixtures"
+      ],
+      "negativeFixture": "an unkeyed POST receiving 503 must not retry"
+    },
+    "FE-RB-004": {
+      "title": "Telemetry sink failure",
+      "gateId": "FE-GATE-024",
+      "triggerKinds": ["TELEMETRY_FAILURE"],
+      "containment": "keep product flow available, bound the queue, and never report recursively to the failing sink",
+      "window": "platform triage planned-default 15m",
+      "escalation": ["observability owner", "telemetry platform owner"],
+      "recoveryEvidence": [
+        "product flow unaffected",
+        "delivery self-check",
+        "queue drained within bound",
+        "forbidden attributes absent"
+      ],
+      "negativeFixture": "raw URL and query data must be removed from telemetry"
+    },
+    "FE-RB-005": {
+      "title": "Coherent release rollback",
+      "gateId": "FE-GATE-025",
+      "triggerKinds": ["RELEASE_BLOCKING_DEFECT"],
+      "containment": "select a prior immutable tuple, verify asset/config/API compatibility, atomically switch, and smoke",
+      "window": "provider recovery target TBD",
+      "escalation": ["release-cache owner", "release approver/hosting owner"],
+      "recoveryEvidence": [
+        "compatibility gate",
+        "release coherence gate",
+        "critical smoke",
+        "release ID in incident timeline"
+      ],
+      "negativeFixture": "HTML build A with asset manifest B must be rejected"
+    }
+  }
+}

config/schemas/field-web-vitals.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "ART-FE-FIELD-WEB-VITALS@1",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "generatedAt",
+    "window",
+    "context",
+    "metrics",
+    "thresholds",
+    "eligibility",
+    "status",
+    "passed"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "window": { "type": "object", "required": ["days", "start", "end"] },
+    "context": {
+      "type": "object",
+      "required": [
+        "source",
+        "sourceSystem",
+        "exportId",
+        "network",
+        "routeAggregation",
+        "releaseId",
+        "privacyApprovalRef",
+        "thresholdDecisionRef",
+        "validationFailures"
+      ],
+      "properties": {
+        "source": { "type": "string" },
+        "sourceSystem": { "type": ["string", "null"] },
+        "exportId": { "type": ["string", "null"] },
+        "network": { "const": "production-real-user" },
+        "routeAggregation": { "const": "route-id-only" },
+        "releaseId": { "type": ["string", "null"] },
+        "privacyApprovalRef": { "type": ["string", "null"] },
+        "thresholdDecisionRef": { "type": ["string", "null"] },
+        "validationFailures": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "thresholds": {
+      "type": "object",
+      "required": [
+        "p75LcpMs",
+        "p75Cls",
+        "p75InpMs",
+        "minimumEligibleSamples"
+      ]
+    },
+    "metrics": {
+      "type": "object",
+      "required": ["p75LcpMs", "p75Cls", "p75InpMs"]
+    },
+    "eligibility": {
+      "type": "object",
+      "required": [
+        "consentRequired",
+        "totalSamples",
+        "eligibleSamples",
+        "minimumEligibleSamples",
+        "routeSamples"
+      ]
+    },
+    "status": {
+      "enum": ["PASS", "FAIL_THRESHOLD", "FAIL_UNVERIFIED"]
+    },
+    "passed": { "type": "boolean" }
+  },
+  "additionalProperties": false
+}

config/schemas/lab-performance.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "ART-FE-LAB@1",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "generatedAt",
+    "context",
+    "metrics",
+    "thresholds",
+    "fixtures",
+    "passed"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "context": {
+      "type": "object",
+      "required": ["runner", "browser", "viewport", "network", "cpu", "cache", "build"]
+    },
+    "metrics": {
+      "type": "object",
+      "required": ["lcpMs", "cls", "namedInteractionMs"]
+    },
+    "thresholds": { "type": "object" },
+    "fixtures": { "type": "array", "minItems": 2 },
+    "passed": { "type": "boolean" }
+  },
+  "additionalProperties": false
+}

config/schemas/release-verification.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "ART-FE-003@1",
+  "type": "object",
+  "required": ["schemaVersion", "generatedAt", "artifact", "fixtures", "passed"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "artifact": {
+      "type": "object",
+      "required": ["checked", "compatible", "mismatches"]
+    },
+    "fixtures": { "type": "array", "minItems": 2 },
+    "passed": { "type": "boolean" }
+  },
+  "additionalProperties": false
+}

config/schemas/runbook-drill-record.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "ART-FE-RUNBOOK-DRILL@1",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "runbookId",
+    "releaseId",
+    "drillTimestamp",
+    "triggerInjected",
+    "triggerAsserted",
+    "containmentAsserted",
+    "escalationPathAsserted",
+    "recoveryAssertions",
+    "negativeFixtureFailedAsExpected",
+    "windowObservedBucket",
+    "passed"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "runbookId": { "pattern": "^FE-RB-00[1-5]$" },
+    "releaseId": { "type": "string", "minLength": 1 },
+    "drillTimestamp": { "type": "string", "format": "date-time" },
+    "triggerInjected": { "type": "string" },
+    "triggerAsserted": { "type": "boolean" },
+    "containmentAsserted": { "type": "boolean" },
+    "escalationPathAsserted": { "type": "boolean" },
+    "recoveryAssertions": {
+      "type": "array",
+      "minItems": 4,
+      "items": {
+        "type": "object",
+        "required": ["assertion", "evidence", "passed"]
+      }
+    },
+    "negativeFixtureFailedAsExpected": { "type": "boolean" },
+    "windowObservedBucket": { "type": "string" },
+    "providerVerificationRequired": { "type": "boolean" },
+    "passed": { "type": "boolean" }
+  },
+  "additionalProperties": false
+}

docs/accessibility/manual-checklist.md

@@ -0,0 +1,51 @@
+# Manual accessibility review checklist
+
+Automated axe checks do not establish WCAG conformance. A human reviewer must
+review all six route records in `artifacts/tests/a11y-manual/` against one
+release candidate and sign them. The required scope is derived from the route
+registry: `APP_HOME`, `EXAMPLES_UI`, `EXAMPLES_STATES`, `EXAMPLES_AUTH`,
+`REFERENCE_RESOURCE_LIST`, and `NOT_FOUND`. Copy the template fields exactly; the
+gate rejects blank identity/timestamp/signature fields, pending verdicts,
+mismatched release IDs, or missing routes.
+
+Allowed item verdicts:
+
+- `pass`
+- `not-applicable (<specific reason>)`
+
+Required record:
+
+```text
+Status: reviewed
+Route ID: APP_HOME
+Release ID: <immutable release ID>
+Reviewer: <human reviewer identity>
+Reviewed at: <RFC 3339 timestamp>
+Signature: <reviewer identity or approved signature reference>
+Attestation: accepted
+M1 Keyboard: pass
+M2 Visible focus: pass
+M3 Route focus: pass
+M4 Modal focus: not-applicable (no modal on this route)
+M5 Error association: not-applicable (no form error on this route)
+M6 Color signal: pass
+M7 Reduced motion: pass
+Screen reader: pass
+Notes: <observations and linked defect IDs>
+```
+
+The reviewer must verify:
+
+- M1: every action works without a pointing device
+- M2: every focused element has a visible indicator
+- M3: route transitions move focus to a deterministic target
+- M4: modal focus is trapped and restored, when a modal exists
+- M5: errors are programmatically associated with their controls, when present
+- M6: state never relies on color alone
+- M7: non-essential motion is suppressed with reduced-motion preference
+- Screen reader: headings, live regions, errors, and actions are announced once
+
+`EXAMPLES_UI` requires real M4 modal and M5 field-error review; those items must
+not be marked not-applicable on that route. Passing automated evidence means
+only that tested pages had no critical or serious axe findings under the
+recorded Chromium, Firefox, and WebKit runs.

docs/architecture/decisions/VD-01-typescript-lint-tooling.md

@@ -0,0 +1,54 @@
+# VD-01: TypeScript 7과 ESLint 10의 점진적 전환 도구
+
+- 상태: Accepted
+- 결정일: 2026-07-26
+- 적용 브랜치: `feature-frontend-typescript-tooling-foundation`
+
+## 배경
+
+저장소는 TypeScript `7.0.2`와 ESLint `10.8.0`을 고정하고 있다. 첫 전환
+브랜치는 compiler를 변경하거나 production source를 일괄 변환하지 않고
+JS/JSX/TS/TSX가 같은 품질 게이트를 통과하게 해야 한다.
+
+결정 시점의 package peer contract는 다음과 같다.
+
+- `typescript-eslint@8.65.0`과 canary는 TypeScript `<6.1.0`을 요구한다.
+- `eslint-plugin-jsx-a11y@6.10.2`는 ESLint `<=9`를 요구한다.
+- `eslint-plugin-react-hooks@7.1.1`은 ESLint 10을 지원한다.
+- Babel 8 ESLint parser는 ESLint 10을 지원하고 Node `>=24.11.0`을 요구한다.
+
+호환되지 않는 peer dependency를 강제 설치하면 lockfile 검증은 통과하더라도
+지원되지 않는 parser와 rule 조합을 플랫폼 계약으로 만들게 된다.
+
+## 결정
+
+1. TypeScript `7.0.2`와 ESLint `10.8.0`을 유지한다.
+2. TypeScript/TSX의 ESLint syntax parsing에는
+   `@babel/eslint-parser`와 TypeScript/JSX syntax plugin을 사용한다.
+3. TypeScript의 이름 해석, unused 진단과 type semantics는 `tsc`가 소유한다.
+   Babel parser가 TypeScript scope manager를 제공하지 않으므로 TS 파일의
+   core `no-undef`와 `no-unused-vars`는 끄고 분리된 app/node/test TypeScript
+   project를 필수 게이트로 실행한다.
+4. React Hook 규칙은 호환되는 `eslint-plugin-react-hooks`로 즉시 적용한다.
+5. JSX 접근성은 현재의 semantic component contract, Testing Library,
+   axe 기반 cross-browser gate와 수동 검토 계약이 계속 담당한다. 호환되지 않는
+   `eslint-plugin-jsx-a11y`는 설치하지 않는다.
+6. Babel 8의 지원 범위에 맞춰 Node engine 하한을 `24.11.0`으로 명시한다.
+7. production source의 대량 rename은 이 결정에 포함하지 않는다.
+
+## 검증
+
+- `check:types`는 app, Node scripts/config, tests project를 모두 검사한다.
+- JS invalid-call, TS invalid port, TS discriminated-union fixture는 실패해야 한다.
+- ESLint와 dependency-cruiser는 TS/TSX architecture fixture를 검사한다.
+- registry scanner는 TS registry의 required field, uniqueness와 reference를
+  검증한다.
+- browser security gate는 TSX의 금지된 raw HTML fixture를 거절한다.
+
+## 후속 검토와 제거
+
+`typescript-eslint`가 TypeScript 7을, JSX 접근성 plugin이 ESLint 10을 공식
+지원하면 별도 dependency 브랜치에서 peer metadata와 전체 negative fixture를
+재검증한다. 교체할 때는 Babel parser package와 TS 전용 ESLint override를
+함께 제거한다. compiler downgrade나 `--force` 설치는 이 ADR의 rollback
+방법이 아니다.

docs/architecture/decisions/VD-03-react-router-data-mode.md

@@ -0,0 +1,58 @@
+# VD-03: React Router Data Mode와 서버 상태 소유권
+
+- 상태: Accepted
+- 결정일: 2026-07-26
+- 적용 브랜치: `feature-frontend-routing-release-recovery-runtime`
+
+## 배경
+
+기존 라우터는 `BrowserRouter`와 수동 JSX route 목록을 사용했다. 직렬화 가능한
+route registry에 params/search schema, loading/error surface, access, title,
+navigation과 chunk ID가 있었지만 실행 route tree와 독립적이어서 선언과 행동이
+어긋날 수 있었다.
+
+이 저장소는 client-only SPA이며 서버 상태는 application input과 TanStack Query가
+소유한다. Framework Mode의 loader/action 중심 데이터 소유권이나 SSR을 도입하지
+않으면서 route object, 오류 경계와 navigation lifecycle은 중앙에서 조립할
+필요가 있다.
+
+## 결정
+
+1. 고정된 React Router `7.18.1`의 `createBrowserRouter`와 `RouterProvider`를
+   사용하는 Data Mode를 기본값으로 채택한다.
+2. 직렬화 가능한 route contract와 React component/codec runtime map을 분리한다.
+3. 모든 executable route object와 navigation은 registry에서 생성한다. JSX에서
+   route 목록을 다시 열거하지 않는다.
+4. params/search는 route 경계의 Zod codec으로 parse하고 같은 codec으로 canonical
+   URL을 생성한다.
+5. loader/action은 같은 서버 데이터를 직접 다시 요청하지 않는다. 필요하면
+   application input 또는 query adapter 한 경로를 호출한다.
+6. 서버 상태, retry, cache와 mutation lifecycle은 application input과 TanStack
+   Query가 계속 소유한다.
+7. lazy chunk rejection만 release recovery input으로 보내며 일반 render error는
+   route/feature boundary가 소유한다.
+8. Framework Mode, SSR, static generation과 router version upgrade는 별도
+   dependency/architecture 브랜치에서 결정한다.
+
+## 검증
+
+- route contract/runtime map의 누락과 orphan은 TypeScript negative fixture와
+  registry gate가 모두 거절한다.
+- duplicate ID/path, unknown codec/surface/chunk와 참조 불일치를 negative registry
+  fixture로 검증한다.
+- params/search parse/build round-trip, canonical redirect, 최대 redirect hop,
+  access rejection, title/focus와 boundary reset을 unit/component test로 검증한다.
+- Vite dynamic entry와 release route chunk map, runtime config JSON Schema를
+  build/release 검증기가 확인한다.
+- chunk failure는 no-store manifest refetch 후 build/release 쌍마다 한 번만
+  reload하며 offline, malformed manifest와 storage 실패는 fail-closed한다.
+
+## 결과와 rollback
+
+Data Router는 navigation lifecycle의 조립 경계이며 서버 데이터 계층이 아니다.
+이 구분을 지키면 React Router를 교체해도 application input과 output port는
+유지된다.
+
+rollback은 RP-04 merge를 되돌려 이전 수동 router와 generic route failure
+surface로 복구한다. URL shape와 application API는 유지하고, 이미 배포된 asset
+cache의 purge는 저장소 rollback 범위에 포함하지 않는다.

docs/architecture/decisions/VD-04-native-form-facade.md

@@ -0,0 +1,55 @@
+# VD-04: Native form controller와 local facade
+
+- 상태: Accepted
+- 결정일: 2026-07-26
+- 적용 브랜치: `feature-frontend-form-page-platform`
+
+## 배경
+
+플랫폼에는 Zod가 이미 설치돼 있지만 form state, field error, dirty navigation과
+page template 계약은 없었다. React Hook Form과 resolver를 바로 추가하면
+dependency와 lockfile이 바뀌고, 현재 reference form에 필요하지 않은 복합 비동기
+field orchestration까지 플랫폼 기본값으로 고정하게 된다.
+
+## 결정
+
+1. RP-06은 React native form event와 controlled value를 사용하는 local
+   `useAppForm` facade를 기본 엔진으로 채택한다.
+2. Zod presentation schema, application command mapper와 domain invariant는 서로
+   다른 소유물로 유지한다.
+3. page와 feature는 `useAppForm`, `Form`, `FormField`, `ErrorSummary`,
+   `mapValidationFailureToFields`, `useDirtyNavigationGuard`만 사용한다.
+4. 422 details는 승인된 `path`와 `code`만 HTTP 경계에서 투영한다. backend
+   message와 알 수 없는 field는 field에 전달하지 않고 안전한 form-level
+   error로 이동한다.
+5. 409 conflict는 validation으로 바꾸지 않으며 입력과 dirty 상태를 보존한다.
+6. pending submit은 동일 controller에서 한 번만 실행하고 success/reset 이후
+   dirty 상태를 해제한다.
+7. `StandardPage`, `CollectionPage`, `DetailPage`, `FormPage`, `StatusPage`는
+   layout과 state slot만 소유하며 application/query/HTTP를 import하지 않는다.
+
+## React Hook Form 도입 조건
+
+다음 중 하나가 실제 제품 요구로 확인되면 local facade 내부 adapter로
+React Hook Form과 Zod resolver를 평가한다.
+
+- 동적 field array와 중첩 object를 함께 다루는 복합 form
+- field 단위 비동기 validation 취소와 의존 validation
+- 수백 개 field의 render isolation이 측정 가능한 병목인 경우
+- uncontrolled input 또는 vendor extension이 필요한 경우
+
+도입하더라도 이 문서의 public API와 component/application tests를 유지해야
+한다. vendor package를 feature/page에서 직접 import하는 것은 허용하지 않는다.
+
+## 검증과 rollback
+
+- client validation, transform/default, 422 allowlist, conflict, duplicate submit,
+  reset, dirty guard와 focus를 component test로 검증한다.
+- template 최소/전체 slot과 async/status variation을 component test로 검증한다.
+- architecture gate가 template의 application/HTTP/query vendor import를
+  거절한다.
+- secret-like input이 URL, storage, diagnostics에 복제되지 않는지 검증한다.
+
+rollback 시 reference page는 이전 직접 form/layout으로 돌아갈 수 있다.
+application input과 outbound gateway 계약은 유지되며, form facade와 template
+commit은 독립적으로 되돌릴 수 있다.

docs/architecture/decisions/VD-05-icon-and-headless-ui.md

@@ -0,0 +1,57 @@
+# VD-05: Semantic icon facade와 native-first interaction
+
+- 상태: Accepted
+- 결정일: 2026-07-26
+- 적용 브랜치: `feature-frontend-design-system-platform`
+- 재검토: native 계약으로 충족할 수 없는 widget 요구가 확인될 때
+
+## 배경
+
+앱 셸과 공통 UI는 문자 glyph, raw button/select와 페이지별 focus 처리를
+사용했다. 아이콘 공급자와 복합 interaction을 제품 코드에 직접 노출하면 번들,
+접근성, vendor type과 교체 비용이 모든 feature로 전파된다. 반대로 실제 요구가
+없는 두 개의 headless vendor를 기본 설치하면 skeleton 소비자가 제거해야 할
+의존성과 중복 interaction 모델이 생긴다.
+
+## 결정
+
+1. 아이콘 공급자는 lockfile 최소 게시 유예를 통과한 `lucide-react@1.25.0`으로
+   고정한다.
+2. `lucide-react`의 static named import는
+   `design-system/icons/vendors/lucide.tsx` 한 파일에서만 허용한다.
+3. public API는 `MenuIcon`, `CloseIcon`, `WarningIcon` 같은 의미 이름만
+   노출한다. vendor component type, icon name, stroke API와 dynamic icon
+   registry는 노출하지 않는다.
+4. 장식 아이콘은 accessibility tree에서 제외한다. 정보를 단독 전달하는
+   아이콘은 `label`, icon-only action은 필수 `accessibleName`을 사용한다.
+5. 현재 복합 control은 native `dialog`, form control, `details`와 local
+   TypeScript state model로 구현한다. Menu는 roving focus/typeahead/Escape,
+   Tabs는 manual/automatic activation, Drawer는 modal/background
+   비활성화/focus restore 계약을 가진다.
+6. React Aria와 Radix는 기본 dependency로 추가하지 않는다. native platform이
+   collision, nested overlay, virtualized collection 또는 복합 select 요구를
+   충족하지 못한다는 재현 가능한 요구가 생길 때 prototype과 ADR로 다시
+   평가한다.
+7. Storybook과 pinned visual baseline은 VD-08/RP-10에서 도입한다. RP-07의
+   runtime gallery와 browser interaction test는 해당 workshop을 대체한다고
+   주장하지 않는다.
+
+## 경계와 검증
+
+- 제품 코드는 `presentation/design-system/index`만 import한다.
+- design-system 검사기는 direct icon/headless import, deep import, raw palette,
+  undefined token과 tooltip-only required information fixture를 거절한다.
+- type negative fixture는 accessible name 없는 `IconButton`을 거절한다.
+- component test는 decorative icon, form control, Menu, Tabs, Drawer와 Toast를
+  검증한다.
+- Chromium/Firefox E2E는 compact Drawer의 native modal 상태, Escape, focus
+  restore, gallery keyboard interaction과 axe를 검증한다.
+- 로컬 WebKit 실행은 host `libevent-2.1.so.7` 부재로 환경 검증이 남아 있으며
+  공급자 선택이나 product behavior의 PASS로 숨기지 않는다.
+
+## Rollback
+
+기존 `presentation/components/ui/*` 경로는 canonical TypeScript primitive를
+재수출하므로 소비 코드를 즉시 되돌릴 수 있다. Lucide 제거 시 vendor facade와
+semantic icon 구현만 교체하고 제품 API는 유지한다. headless vendor를 나중에
+도입해도 public props와 interaction test를 유지한다.

docs/architecture/decisions/VD-06-intl-typed-message-catalog.md

@@ -0,0 +1,96 @@
+# VD-06: Intl과 typed local message catalog
+
+- 상태: Accepted
+- 결정일: 2026-07-26
+- 적용 브랜치: `feature-frontend-i18n-message-formatting-contract`
+- 재검토: 승인 locale·복수형 문법·번역 추출 workflow가 local catalog 범위를 넘을 때
+
+## 배경
+
+공통 셸, route surface, async/form 상태와 디자인 시스템 기본 문구가 JSX와
+JavaScript에 분산돼 있었다. 날짜는 일부 application mapper에서 고정 locale로
+가공되어 presentation이 locale을 바꿀 수 없었고, direction·누락 key·보간 실패
+정책도 없었다. 반면 현재 skeleton에는 번역 관리 서비스, 실제 번역 승인 절차,
+복잡한 ICU 문법이라는 제품 요구가 아직 없다. 이 단계에서 i18n vendor를 기본
+번들에 넣으면 소비 프로젝트가 제거하거나 다시 감싸야 할 의존성만 늘어난다.
+
+## 결정
+
+1. 표준 `Intl.DateTimeFormat`, `NumberFormat`, `RelativeTimeFormat`,
+   `ListFormat`, `PluralRules`와 typed local catalog를 기본 엔진으로 사용한다.
+2. `MessageKey`는 한국어 canonical catalog에서 도출하며 영어와 RTL smoke
+   catalog는 `satisfies Record<MessageKey, string>`으로 compile-time parity를
+   강제한다.
+3. 보간이 필요한 key는 `MessageParameters`에 key별 parameter object를
+   선언한다. 잘못된 key, 누락·초과 parameter는 TypeScript negative fixture가
+   거절한다.
+4. 기본 locale은 `ko-KR`, fallback locale도 `ko-KR`이다. 알려지지 않은 locale은
+   language fallback 후 `ko-KR`로 정규화한다. 알려지지 않은 key와 누락 보간은
+   raw key나 외부 값을 출력하지 않고 안전한 공통 fallback을 반환한다.
+5. `en-XA`는 영어 문구를 확장·accent 처리하는 pseudo locale이고 `ar-EG`는
+   RTL 동작 smoke locale이다. 이 두 locale은 실제 제품 번역 완료를 의미하지
+   않는다.
+6. 날짜 formatter의 기본 timezone은 테스트와 SSR/브라우저 결과가 흔들리지
+   않도록 `UTC`다. 제품 timezone이 필요하면 호출자가 명시한다. invalid
+   date/number/timezone은 `—`를 반환하고 throw하지 않는다.
+7. locale state는 React inbound concern이다. `LocaleProvider`가 copy,
+   formatter와 `<html lang/dir>`을 제공하며 application/domain은 미리 번역된
+   문자열 대신 의미 값과 timestamp를 반환한다.
+8. backend `message`, raw HTML, stack과 내부 key를 catalog 입력으로 신뢰하지
+   않는다. transport/application failure kind를 등록된 사용자 message key로
+   매핑한 뒤 presentation이 해석한다.
+9. key rename은 즉시 제거하지 않고 `MESSAGE_KEY_ALIASES`에 compatibility alias를
+   둔다. alias는 새 호출의 타입에 포함하지 않아 신규 코드는 canonical key만
+   사용한다.
+10. extraction, ICU rich message, 번역 SaaS 또는 framework adapter가 필요해지면
+    `presentation/i18n` public API 뒤에서 교체한다. vendor type은 feature와
+    design-system public prop으로 노출하지 않는다.
+
+## 실행 경계
+
+```text
+route/form/failure 의미 값
+  -> presentation message key
+  -> LocaleProvider
+  -> typed catalog / Intl formatter
+  -> text node와 accessible name
+```
+
+- canonical catalog: `src/presentation/i18n/catalog.ts`
+- feature contribution: `src/features/*/contracts/*-message-catalog.js`를
+  `src/features/installed-feature-messages.js`에서 조립
+- key/보간/fallback/alias: `message-contract.ts`
+- locale-safe value formatting: `formatters.ts`
+- React composition과 document metadata: `locale-provider.tsx`
+- public entry: `src/presentation/i18n/index.ts`
+
+## 검증
+
+- `check:i18n`은 catalog key와 placeholder parity, common UI의 한국어 literal,
+  backend message JSX 렌더링과 raw HTML 사용을 검사한다.
+- `check:i18n:fixture`는 세 금지 사례를 실제로 거절해야 성공으로 인정된다.
+- type negative fixture는 unknown key와 잘못된 parameter shape를 거절한다.
+- unit test는 fallback, alias, pseudo 확장, direction과 timezone/number/relative/
+  list/plural/select의 결정성을 검증한다.
+- component test는 document `lang/dir`, RTL Tabs와 direction-aware pagination,
+  Drawer semantics를 검증한다.
+- Playwright는 320px pseudo reflow와 RTL compact shell/Drawer/focus restore를
+  Chromium, Firefox, WebKit project에서 실행한다.
+
+## 한계와 재검토 조건
+
+현재 catalog는 실제 번역 승인, ICU rich text, locale별 plural 문장 전체 조합,
+메시지 추출/번역 메모리와 서버 locale negotiation을 제공하지 않는다. 다음 중
+하나가 확인되면 별도 ADR로 엔진을 재평가한다.
+
+- 세 개 이상의 실제 승인 locale과 번역 담당 workflow
+- 복수형·성별·select가 한 문장 안에서 중첩되는 제품 copy
+- server/client extraction, namespace lazy-loading 또는 번역 SaaS 연동
+- SSR locale negotiation과 hydration 일치가 필요한 rendering mode
+
+## Rollback
+
+`ko-KR` catalog가 기존 기본 문구를 보존하므로 provider를 고정 locale adapter로
+되돌려도 기본 UX를 유지한다. formatter/vendor 교체 시 public `message`,
+`date`, `number`, `relativeTime`, `list`, `plural`, `select` 계약과 negative
+fixture는 유지한다. alias는 migration window 종료 근거 없이 제거하지 않는다.

docs/architecture/decisions/VD-07-diagnostics-and-telemetry-exporter.md

@@ -0,0 +1,97 @@
+# VD-07: Diagnostics와 telemetry exporter 경계
+
+- 상태: Accepted
+- 결정일: 2026-07-26
+- 적용 브랜치: `feature-frontend-diagnostics-telemetry-runtime`
+- 재검토: 실제 운영 sink, consent가 필요한 analytics 또는 분산 tracing provider가
+  선정될 때
+
+## 배경
+
+기존 telemetry registry와 best-effort HTTP queue는 있었지만 운영 진단 record와
+semantic event의 책임이 하나의 telemetry port에 섞여 있었다. boot, HTTP,
+cache, storage, route와 release failure의 선언도 실제 production producer와
+완전히 연결되지 않았다. 이 상태에서는 retry attempt마다 같은 사건을 발행하거나
+raw URL, query, request body와 오류 객체가 queue에 들어갈 위험이 있다.
+
+반면 skeleton 단계에는 실제 관측 vendor, endpoint의 운영 보안 정책, analytics
+consent와 보존 기간이 결정되지 않았다. 특정 SDK를 기본 번들에 설치하는 것은
+vendor 결정 전에는 안전한 기본값이 아니다.
+
+## 결정
+
+1. level 기반 운영 진단은 `DiagnosticsPort`, registry 기반 semantic event는
+   `TelemetryPort`로 분리한다. application은 두 port의 concrete adapter나
+   exporter SDK를 알지 못한다.
+2. diagnostics의 level, event ID와 context key는 닫힌 registry/allowlist다.
+   telemetry도 event별 required/optional attribute와 value policy를 적용한다.
+   등록되지 않은 event·context·고카디널리티 값은 전송하지 않는다.
+3. 기본 diagnostics adapter는 bounded in-memory evidence이고 telemetry는
+   설정이 없으면 true no-op이다. endpoint가 있을 때만 bounded oldest-drop
+   queue와 best-effort HTTP sink를 사용한다.
+4. raw path/URL/query/body/response/storage value, credential, cookie, email,
+   stack과 오류 객체 전체는 context에 넣지 않는다. route ID, operation ID,
+   correlation ID, release ID, error kind, status/attempt/duration bucket만
+   허용한다.
+5. HTTP logical execution은 success, retry recovery, terminal failure 또는
+   abort마다 `http.request.completed` diagnostics를 정확히 한 번 남긴다.
+   `api.request.failed` telemetry는 retry가 끝난 terminal non-abort failure에만
+   정확히 한 번 발행한다.
+6. `app.boot.failed`, `ui.render.failed`, `release.mismatch.detected`,
+   `telemetry.delivery.dropped`를 production path에 연결한다. cache와 storage
+   실패는 diagnostics로 기록하되 raw key/value를 기록하지 않는다.
+7. queue full, invalid event/context, serialization과 sink failure는 제한된
+   reason bucket으로 집계한다. drop observer의 failure는 다시 telemetry를
+   발행하지 않는 nonrecursive 경계다.
+8. diagnostics와 telemetry failure는 제품 흐름, HTTP 결과, route transition,
+   storage/cache fallback과 React error surface를 바꾸지 않는다.
+9. mount 전 bootstrap failure는 안전한 build/config/error kind만 별도 evidence로
+   만들며 untrusted error message, stack과 support 입력을 serialize하지 않는다.
+10. 실제 error reporter, RUM, analytics나 tracing SDK는 같은 port 뒤의 외부
+    adapter로만 추가한다. SDK type과 event API를 application/feature/presentation
+    public contract에 노출하지 않는다.
+
+## 실행 경계
+
+```text
+route/application/HTTP/cache/storage/bootstrap
+  -> typed DiagnosticsPort 또는 TelemetryPort
+  -> registry + allowlist + value policy
+  -> bounded memory/no-op 또는 best-effort HTTP adapter
+  -> 프로젝트가 선택한 외부 sink
+```
+
+- diagnostics contract: `src/contracts/diagnostics.ts`
+- telemetry contract: `src/contracts/telemetry.js`
+- application ports: `src/application/ports/diagnostics-port.ts`,
+  `telemetry-port.ts`
+- bounded diagnostics: `src/adapters/diagnostics/bounded-diagnostics.ts`
+- best-effort telemetry: `src/adapters/telemetry/best-effort-telemetry.js`
+- composition: `src/bootstrap/runtime-adapters.js`
+
+## 검증
+
+- `check:diagnostics`는 모든 registry event에 production producer가 있는지와
+  source의 direct console/sensitive context 우회를 검사한다.
+- negative source fixture는 direct console, unknown event와 raw context를 실제로
+  거절하며 TypeScript fixture는 잘못된 level/event ID를 거절한다.
+- unit test는 allowlist, hostile/circular error, bounded diagnostics, no-op,
+  queue full, sink/observer failure와 pre-mount boot evidence를 검증한다.
+- HTTP integration은 success, retry recovery, terminal failure와 abort의 producer
+  횟수, route/operation/correlation context와 요청 값 비노출을 검증한다.
+- cache/storage/release/application/runtime test는 각 production wiring과
+  diagnostics failure isolation을 검증한다.
+
+## 한계와 재검토 조건
+
+기본 adapter는 운영 log 검색, source map 연계, session replay, distributed span,
+analytics consent, sampling budget과 장기 보존을 제공하지 않는다. 실제 sink를
+선정할 때 데이터 처리 지역, 보존 기간, consent, CSP, source map 접근 제어,
+sampling과 비용 상한을 별도 결정해야 한다.
+
+## Rollback
+
+telemetry exporter는 runtime 설정을 끄거나 adapter wiring을 `noOpTelemetry`로
+바꾸어 독립적으로 제거할 수 있다. 이때도 `DiagnosticsPort`, registry,
+redaction/value policy, producer-count와 negative fixture는 유지한다. 외부 SDK
+문제로 application producer와 안전 계약을 함께 되돌리지 않는다.

docs/architecture/frontend-platform-capability-review.md

@@ -0,0 +1,475 @@
+# 프론트엔드 플랫폼 역량 재검토
+
+## 1. 문서 목적
+
+이 문서는 도메인 기능과 실제 운영 환경의 배포 증적을 제외하고, 이 저장소가 새
+프론트엔드 제품의 출발점으로 제공해야 하는 공통 역량을 다시 평가한다. 평가
+기준은 다음과 같다.
+
+- 코드나 설정 파일이 존재하는지만 보지 않는다.
+- 부트스트랩부터 화면까지 실제 호출 경로가 연결되는지 확인한다.
+- 선언한 레지스트리와 정책이 런타임 및 CI에서 집행되는지 확인한다.
+- 기본 번들에 포함할 역량과 필요할 때 설치할 확장 역량을 구분한다.
+- 특정 벤더를 채택하더라도 제품 코드가 벤더 API에 직접 결합되지 않는지 확인한다.
+
+최초 검토 기준은 `develop`의 `cb195f8`이며, RP-01~RP-08 구현 결과를 이 문서에
+누적 반영했다. 이후 구현으로 경로나 세부 내용이 달라질 수 있으므로, 각 항목은
+문서의 경로뿐 아니라 해당 테스트와 아키텍처 게이트로 계속 검증해야 한다.
+
+## 2. 결론
+
+현재 저장소는 다음 기반이 강하다.
+
+- 런타임 설정과 릴리스 매니페스트 검증
+- 도메인, 애플리케이션, 프레젠테이션, outbound adapter의 의존 방향
+- 공통 HTTP 실패 형태와 제한된 retry 정책
+- 앱 셸, 반응형 내비게이션, 테마, 비동기 상태 표면
+- Vitest, Testing Library, MSW, Playwright, axe를 이용한 테스트 계층
+- CI 게이트 taxonomy와 호환성·보안·성능·릴리스 계약 문서
+
+그러나 “도메인 기능을 바로 추가할 수 있는 프론트엔드 플랫폼” 기준으로는 아직
+중요한 연결부가 빠져 있다. 가장 큰 문제는 공통 기능이 없다는 것보다 이미 있는
+기능이 실제 기능 화면의 표준 호출 경로로 조립되지 않았다는 점이다.
+
+특히 다음은 선행 해결이 필요하다.
+
+RP-01~RP-09에서 TypeScript 도구 안전망, application runtime 주입,
+query/mutation inbound adapter, HTTP 실행 계약과 executable route/release
+recovery 계약, 제거 가능한 reference 수직 슬라이스, form/page, design system과
+i18n 실행 경계와 diagnostics/telemetry production wiring은 구현됐다. 현재 선행 해결
+대상은 다음과 같다.
+
+1. registry evidence와 실제 compatibility diff
+2. 공급망과 optional adapter recipe 심화 게이트
+
+따라서 현재 상태를 “프론트 공통부가 모두 구현됐다”고 표현하면 범위가 과장된다.
+더 정확한 표현은 다음과 같다.
+
+> 운영·안전 계약과 범용 앱 셸은 갖춰졌지만, 기능 개발자가 사용하는 application
+> API, 서버 상태, 폼, 라우팅, 페이지 패턴의 표준 수직 경로는 아직 보강이
+> 필요하다.
+
+## 3. 판정 기준
+
+| 판정 | 의미 |
+| --- | --- |
+| 준비됨 | 구현, 실제 조립, 자동 검증이 모두 존재한다. |
+| 부분 준비 | 핵심 구현은 있으나 실제 호출 경로, 정책 집행, 예제가 불완전하다. |
+| 미제공 | 새 기능을 만들 때 팀이 직접 선택·설계해야 한다. |
+| 프로젝트 선택 | 기본 번들에 강제하면 비용이 더 크며, 경계와 recipe만 제공한다. |
+
+## 4. 역량 매트릭스
+
+| 영역 | 현재 판정 | 근거 | 필요한 다음 상태 |
+| --- | --- | --- | --- |
+| 부트·런타임 설정 | 준비됨 | `src/bootstrap`, runtime schema, release 검사 | 현 상태 유지, TS 전환 시 동일 게이트 유지 |
+| 계층 의존 방향 | 부분 준비 | `.dependency-cruiser.cjs`, `src/application/ports` | inbound/outbound 명명과 `contracts` 소유권까지 집행 |
+| application facade | 준비됨 | typed input/output catalog, provider, production composition test | feature input use case를 contribution으로 확장 |
+| HTTP client | 준비됨 | path/search/body projection, runtime timeout/retry, abort/cleanup test | feature gateway 뒤에서 사용 |
+| retry | 준비됨 | HTTP 단일 소유, runtime max attempts, Query retry off, logical execution당 bounded diagnostics | terminal event 중복 방지 계약 유지 |
+| 오류 모델 | 부분 준비 | error registry와 normalization 존재 | typed discriminated union과 계층별 mapper |
+| 검증 | 준비됨 | runtime/API/route/form Zod parse 결과를 실행 경계에서 사용하고 domain invariant와 분리 | feature별 schema 소유권 유지 |
+| 인증 연동 | 준비됨/프로젝트 선택 | opaque auth owner와 demo seam 존재 | 인증 방식별 recipe; 기본 token 저장소는 추가하지 않음 |
+| 서버 상태 | 준비됨 | reference route의 query/mutation, cancellation, stale, optimistic/conflict/rollback | feature별 query contribution recipe 유지 |
+| 클라이언트 상태 | 부분 준비 | local state, theme context, session external store | 상태 소유권 표와 typed external-store 예제 |
+| 범용 global store | 프로젝트 선택 | 별도 라이브러리 없음 | 필요 조건에 따라 Zustand/Redux Toolkit/state machine 선택 |
+| 라우팅 | 준비됨 | Data Router, typed runtime map, codec, metadata consumer, bounded chunk recovery | reference feature route와 release E2E로 사용 범위 확장 |
+| 앱 셸·반응형 | 준비됨 | native modal Drawer, compact/desktop layout, Escape/link dismiss/focus restore, pseudo reflow와 RTL direction | compact browser matrix 유지 |
+| 페이지 템플릿 | 준비됨 | Standard/Collection/Detail/Form/Status와 public design-system entry | feature별 slot 조합 유지 |
+| 디자인 토큰 | 준비됨 | primitive/semantic/component CSS, 48-token 자동 계약, dark/forced-colors/reduced-motion | 제품 brand token은 외부 프로젝트에서 확장 |
+| 공통 UI | 준비됨 | action/form/feedback/overlay/navigation primitive와 pattern, compatibility export | Storybook/visual은 RP-10 |
+| 아이콘 | 준비됨 | Lucide static vendor facade와 semantic icon/IconButton 접근성 계약 | 의미 icon 추가 시 bundle/접근성 기준 적용 |
+| 폼 | 준비됨 | Zod 기반 local facade, error summary/focus, 422 allowlist, dirty/pending/conflict 정책 | 복합 form 요구가 생기면 VD-04 조건으로 vendor adapter 평가 |
+| 국제화 | 준비됨 | 137-key typed catalog, locale provider, Intl formatter, safe fallback/alias, pseudo·RTL gate | 실제 locale·번역 승인은 프로젝트에서 연결 |
+| logging/diagnostics | 준비됨 | 별도 `DiagnosticsPort`, 8-event registry, allowlist, bounded/no-op adapter와 production producer | 실제 프로젝트의 remote sink는 port 뒤에서 선택 |
+| telemetry | 준비됨/프로젝트 선택 | 5-event registry, bounded queue, redaction/value policy, boot·HTTP·render·release·drop producer | analytics/RUM/error vendor와 consent는 프로젝트에서 선택 |
+| 비동기 상태 불변식 | 준비됨 | 배타적 typed overlay, stale latch, 실제 retry/conflict action | reference 화면에서 전체 상태 전시 |
+| 단위·통합·E2E | 준비됨 | Vitest, RTL, MSW, Playwright 3엔진 | TS 테스트 검사, 실제 bootstrap 통합, 위험 시나리오 보강 |
+| UI 회귀 검증 | 미제공 | axe/reflow는 있으나 visual baseline 없음 | Storybook 또는 동급 workshop과 시각 회귀 |
+| 샘플 제거 | 준비됨 | feature/catalog/test 제거 후 type/architecture/registry/test/home/build 8단계 검증 | 새 contribution도 같은 제거 gate에 포함 |
+| registry·compatibility 집행 | 부분 준비 | registry와 gate는 있으나 실제 before/after 및 orphan 검사가 제한적 | type/reference/orphan/diff/migration을 자동 검증 |
+| 공급망 검사 | 부분 준비 | lockfile·문서·gate는 있으나 실제 transitive 취약점/license/SBOM 깊이가 부족 | pinned scanner와 policy exception/증적 연결 |
+| realtime·offline·file 등 | 프로젝트 선택 | 현재 없음 | port/adapter recipe와 선택 기준 제공 |
+
+## 5. 우선순위별 발견 사항
+
+### 5.1 P0: 기능 개발을 막는 항목
+
+#### RP-02에서 application 런타임 우회 해결
+
+`src/bootstrap/composition-root.js`가 만든 typed application input API는
+production `ApplicationProvider`에 주입된다. raw auth, storage, telemetry와
+release port는 closure 안에 남고 UI는 session, preference, diagnostics와 runtime
+query만 사용한다.
+
+목표 상태:
+
+- `Application`은 UI가 호출할 query/command use case를 제공한다.
+- `ApplicationProvider`는 이 API만 React tree에 제공한다.
+- 페이지는 HTTP, storage, auth SDK, telemetry sink를 직접 호출하지 않는다.
+- bootstrap만 concrete outbound adapter를 알고 조합한다.
+- 실제 bootstrap부터 reference page까지 연결한 통합 테스트가 있다.
+
+#### RP-03에서 표준 서버 상태 bridge 구현
+
+`src/presentation/adapters/query` 한 경계만 `@tanstack/**`를 import한다.
+`useApplicationQuery`와 `useApplicationMutation`은 application result를 React
+lifecycle에 연결하며 cancellation, stale failure, duplicate submit, optimistic
+rollback, conflict resolution과 invalidation을 검증한다. 다른 presentation
+경로의 직접 TanStack import는 negative fixture가 거절한다.
+
+목표 상태:
+
+- canonical target인 `src/adapters/inbound/react/platform/query`에 벤더 연동을
+  한정한다. 마이그레이션 중에는 기존 `presentation`을 같은 inbound 경계로
+  취급하되 새 대체 경로를 만들지 않는다.
+- `useApplicationQuery`, `useApplicationMutation` 또는 같은 역할의 typed
+  controller hook을 제공한다.
+- HTTP retry와 query retry 중 한 계층만 재시도 책임을 갖는다.
+- loading, empty, refreshing, stale, offline, error, conflict, optimistic rollback을
+  reference feature에서 보여 준다.
+
+#### RP-01에서 TypeScript 검사 도구 안전망 구현
+
+현재 source는 모두 JS/JSX이고 `strict + allowJs + checkJs`를 사용한다. 이는 좋은
+중간 안전망이지만 다음 도구는 TS migration을 그대로 따라가지 못한다.
+
+- ESLint의 계층·보안 glob은 JS/JSX 중심이다.
+- registry scanner는 `.ts`와 `.tsx`를 찾지 않는다.
+- registry governance 경로가 `.js` 확장자로 고정되어 있다.
+- tests는 현재 `tsconfig.json` 검사 범위에서 빠진다.
+
+따라서 파일 확장자를 먼저 바꾸면 새 TS 코드가 일부 자동 검사에서 빠질 수 있다.
+TypeScript 전환은
+[TypeScript의 JavaScript migration 가이드](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html)
+처럼 점진적으로 진행하되, 이 저장소에서는 tooling glob과 CI를 먼저 고쳐야 한다.
+
+#### RP-03에서 HTTP 선언과 실행의 차이 해결
+
+HTTP request builder는 path segment escaping, canonical optional/array search,
+Zod default/trim 결과의 실제 query/body 전송을 담당한다. runtime timeout과
+0/1/N max retry가 client factory에 주입되고 caller abort와 timeout을 다른 typed
+failure로 투영한다. validation 조기 반환은 fetch/timer 0회이며 success, schema
+failure, abort, timeout과 exhausted retry는 scheduler/listener cleanup을
+검증한다. HTTP 사건의 semantic telemetry 연결은 RP-09 범위다.
+
+client를 거대한 범용 함수로 계속 확장하지 말고 transport, request builder, auth,
+timeout, retry, decoder, mapper 책임을 분리해야 한다. application에는 범용 HTTP
+메서드보다 feature가 요구하는 gateway interface를 노출한다.
+
+#### RP-04에서 route registry를 실행 계약으로 전환
+
+platform route 계약과 `src/features/installed-feature-contracts.js`의 직렬화
+가능한 contribution을 기준으로
+`src/presentation/routes/app-router.tsx`가 Data Router route object와
+navigation을 생성한다. `route-runtime.tsx`는 lazy component의 실행 map만
+소유하며 contract/runtime 누락과 orphan은 TypeScript negative fixture와 registry
+gate가 모두 거절한다.
+
+현재 보장:
+
+- serializable contract와 executable runtime map을 분리한다.
+- `satisfies Record<RouteId, RouteRuntime>`로 양방향 완전성을 검사한다.
+- params/search는 Zod codec으로 경계에서 parse하고 URL builder도 같은 codec을
+  사용한다.
+- loading/error/chunk/access/title/navigation metadata를 실제 route object에
+  연결한다.
+- route change 시 boundary reset, title, focus와 scroll을 검증한다.
+- Vite manifest의 실제 dynamic entry와 route chunk ID를 release manifest에
+  연결하고, no-store manifest 재조회와 build/release 쌍별 1회 reload를
+  production application input까지 연결한다.
+
+#### RP-05에서 제거 가능한 reference feature 구현
+
+`src/features/reference-feature`가 domain, application input, outbound gateway,
+DTO/schema, mapper, route/API/query contract, query/mutation controller와 page를
+한 소유 경계에 둔다. production composition은 generic feature input catalog를
+통해 이 input을 주입하며 UI는 HTTP나 output port를 직접 보지 않는다.
+
+`test:sample-removal`은 임시 복제본에서 feature source/tests를 삭제하고 installed
+contract/runtime/adapter catalog를 빈 목록으로 재생성한다. 그 뒤 typecheck,
+architecture, registry, unit/integration, home smoke, build와 fixture ID 잔여
+0개를 검사한다. 설치 모드에서는 MSW를 사용한 bootstrap → router → application
+→ HTTP → schema → mapper → query cache → page 수직 테스트가 실행된다.
+
+#### 비동기·복구 상태의 불변식이 닫혀 있지 않다
+
+공통 async model과 gallery가 있지만 선언 가능한 상태 조합 중 일부는 사용자
+행동과 모순될 수 있다. stale data가 있는 degraded 상태와 refreshing, mutation
+pending과 conflict, retry button과 실제 handler 존재 여부를 typed state로
+닫아야 한다. 상태를 boolean 여러 개로 조합하지 않고 다음과 같은 discriminated
+state와 action capability로 표현한다.
+
+```text
+initial-loading
+ready
+refreshing-with-data
+empty
+degraded-with-data
+terminal-error
+mutation-pending
+mutation-conflict
+```
+
+RP-04에서 lazy import failure는 `ChunkRecoveryBoundary` → application recovery
+input → `ReleaseInfoPort.refresh()`의 no-store manifest 조회 → build/release 쌍
+guard → browser navigation adapter의 1회 reload로 연결됐다. 일반 render
+failure는 이 경로에서 제외되고, 반복 실패·offline·malformed manifest·storage
+실패는 지원 표면으로 fail-closed된다.
+
+#### RP-09에서 diagnostics/telemetry 실행 깊이 보강
+
+`DiagnosticsPort`와 `TelemetryPort`를 분리하고 boot, HTTP logical outcome,
+render, cache, storage, route, release mismatch와 delivery drop을 production
+producer에 연결했다. HTTP retry는 attempt별 terminal event를 발행하지 않고
+logical execution 종료 시 한 번만 bounded outcome을 남긴다. allowlist와
+value policy가 raw URL/query/body/storage value/error object를 거절하고 queue와
+sink failure는 nonrecursive drop evidence로 제한된다.
+
+registry/compatibility 검사는 다음까지 확장한다.
+
+- ID와 enum/type의 양방향 완전성
+- referenced schema/message/token의 존재
+- 실행 코드에서 소비되지 않는 orphan 항목
+- 기준 commit과 현재 commit 사이의 실제 contract diff
+- breaking change의 version/migration/rollback metadata
+
+공급망 검사는 단순 문자열 secret 탐지에 머물지 않고 transitive dependency,
+known vulnerability, license policy, SBOM/provenance를 pinned tool로 검사해야 한다.
+도구 장애와 취약점 발견을 구분하고, 예외에는 owner·사유·만료일을 요구한다.
+
+### 5.2 P1: 공통 플랫폼 기본 제공 항목
+
+- RP-06에서 완료한 schema 기반 form facade와 field/error/pending/dirty/422 정책 유지
+- RP-06에서 완료한 standard, collection, detail, form, status page template의 public entry 정리
+- 접근 가능한 drawer, menu, popover, select 같은 interaction primitive
+- token → primitive → pattern → template로 이어지는 디자인 시스템
+- Lucide를 감싼 local icon registry와 `IconButton`
+- typed message key, locale provider, formatter, pseudo-locale/RTL smoke
+- RP-09에서 완료한 redacted structured diagnostics와 telemetry wiring 유지
+- Storybook 또는 동급 isolated UI workshop
+- Playwright visual baseline, shared MSW scenarios, built-dist E2E
+- React Hooks, JSX accessibility, TanStack Query 관련 lint
+- source와 tests를 모두 포함하는 TypeScript project references
+- registry/compatibility의 실제 diff와 orphan reference 검사
+- transitive vulnerability, license, SBOM/provenance 공급망 gate
+
+#### RP-08에서 국제화 실행 경계 구현
+
+`src/presentation/i18n`은 shell, route, async/form error, page template와
+design-system 기본 copy의 canonical 경계다. `MessageKey`와 key별
+`MessageParameters`가 잘못된 key/보간을 compile time에 막고, runtime
+`resolveMessage`는 unknown locale/key와 누락 보간에서 raw 값 대신 안전한
+fallback을 반환한다. application mapper는 locale-formatted date를 반환하지
+않고 timestamp를 유지하며 presentation formatter가 `UTC` 또는 명시 timezone을
+적용한다.
+
+`LocaleProvider`는 `ko-KR`, `en-US`, `en-XA`, `ar-EG` smoke set과 document
+`lang/dir`을 동기화한다. `en-XA`는 긴 문구 reflow, `ar-EG`는 logical CSS,
+Drawer, Tabs arrow와 pagination 방향 icon을 검증하기 위한 개발 locale이다.
+실제 아랍어 번역 완료를 뜻하지 않는다. `check:i18n`과 negative fixture는 common
+UI literal, backend raw message render와 raw HTML interpolation을 거절한다.
+새 key rename은 canonical type에는 넣지 않고 runtime alias/migration window로
+호환한다.
+
+### 5.3 P2: 경계와 recipe를 제공할 선택 항목
+
+다음 기능을 모든 앱의 초기 번들에 설치할 필요는 없다. 대신 port 또는 local
+vendor facade, 선택 조건, 실패 정책, 테스트 fixture를 문서로 제공한다.
+
+| capability | 대표 기술 | 기본 제공할 경계 | 실제 설치 조건 |
+| --- | --- | --- | --- |
+| realtime | WebSocket, SSE | subscribe/unsubscribe, reconnect, resume, heartbeat | 서버가 push event를 제공할 때 |
+| offline storage | IndexedDB | versioned repository, migration, quota failure | offline read/write가 제품 요구일 때 |
+| background/cache | Service Worker, PWA | cache ownership, update, rollback recipe | installable/offline 앱일 때 |
+| file transfer | presigned HTTP, multipart | progress, cancel, size/type validation | 업로드·대용량 다운로드가 있을 때 |
+| generated API | OpenAPI, GraphQL, gRPC-Web | generated client를 gateway 뒤에 감싸는 규칙 | 서버 계약 형식이 확정됐을 때 |
+| feature flag | local/remote flag provider | typed flag key, default, stale behavior | staged rollout가 필요할 때 |
+| worker | Web Worker | request/result/cancel protocol | UI thread를 막는 CPU 작업이 있을 때 |
+| multi-tab | BroadcastChannel | event versioning, source ID, conflict policy | 탭 간 동기화가 필요할 때 |
+| browser capability | clipboard, notification, media | permission/result port | 해당 UX가 있을 때 |
+| client workflow | Zustand, Redux Toolkit, state machine | state ownership decision과 local facade | cross-feature workflow가 실제로 생길 때 |
+| large data UI | virtualization, data grid | owned component facade | 데이터 규모가 측정 기준을 넘을 때 |
+| analytics/error sink | vendor SDK, OpenTelemetry | redaction, consent, sampling adapter | 운영 provider와 정책이 정해졌을 때 |
+
+서버의 Redis, MongoDB, PostgreSQL, MinIO를 브라우저가 직접 연결하는 구조는 기본
+frontend adapter catalog에 넣지 않는다. 브라우저는 권한 있는 backend API/BFF를
+통해 이 자원에 접근해야 한다. 프론트에서 대응되는 변화 지점은 데이터베이스
+vendor가 아니라 HTTP/GraphQL/gRPC-Web, realtime, file transfer, cache, storage,
+worker, browser capability 같은 프로토콜·런타임 capability다.
+
+### 성능 최적화는 모두 adapter 문제인가
+
+아니다. 먼저 측정하고 병목의 소유 계층에 맞는 수단을 적용한다.
+
+| 문제 | 기본 제공할 수단 | adapter/facade가 필요한 경우 |
+| --- | --- | --- |
+| 초기 JS가 큼 | route/feature lazy loading, bundle budget, dependency inventory | remote module이나 별도 delivery 전략이 있을 때 |
+| 중복 네트워크 | TanStack deduplication/cache, abort, bounded retry | offline cache나 generated client를 교체할 때 |
+| 느린 화면 전환 | prefetch policy, stable shell, cached-data surface | route별 prefetch provider가 필요할 때 |
+| 긴 main-thread task | profiler 기준으로 계산 분리 | Web Worker message adapter |
+| 대량 목록 | pagination과 server filter를 우선 | virtualizer/data-grid facade |
+| 이미지 전송량 | width/height, lazy loading, responsive source 규칙 | Image CDN URL builder adapter |
+| 재방문/offline | HTTP cache contract | Service Worker/IndexedDB adapter |
+| 불필요한 render | 상태 소유권 축소와 component boundary | 보통 adapter가 아니며 측정 후 memoization |
+
+기본 skeleton은 bundle budget, lazy route, query cancellation/cache, responsive
+image 규칙, stable layout, lab performance test를 제공한다. Web Worker,
+virtualization, Image CDN, Service Worker는 실제 병목과 제품 요구가 확인될 때
+설치한다. 라이브러리를 미리 많이 넣는 것은 최적화가 아니라 초기 번들·공급망
+표면을 늘리는 일이 될 수 있다.
+
+## 6. 질문별 직접 답변
+
+### 프론트도 inbound/outbound로 나누는가
+
+나눈다. 현재 구조에서는 `presentation`이 사실상 inbound adapter이고
+`src/adapters`가 outbound adapter다. 이름과 문서가 이 역할을 명확히 드러내지
+않아 모두 같은 adapter처럼 보인 것이다.
+
+| 역할 | 프론트 예 |
+| --- | --- |
+| input/inbound port | `ListResources`, `CreateResource` 같은 application API |
+| inbound adapter | React page/controller, router, form event, push-event translator |
+| output/outbound port | resource gateway, session, storage, clock, diagnostics |
+| outbound adapter | HTTP, auth SDK, browser storage, TanStack cache, telemetry sink |
+
+React, router, form library, icon library마다 application port를 만들 필요는 없다.
+UI 내부 교체만 필요한 라이브러리는 React inbound adapter 내부 vendor facade로
+충분하다. port는 application 정책과 외부 소유권 사이의 경계에 둔다.
+
+### 왜 현재 모두 `adapters` 아래에 있는가
+
+실제로 모두 있지는 않다. UI driver가 `presentation`이라는 이름으로 분리돼 있고,
+`adapters`에는 주로 outbound 구현이 있다. 다만 다음 두 대안 중 하나를 명시적으로
+선택해야 한다.
+
+1. 변경량을 줄여 `presentation = inbound adapter`로 문서화하고
+   `adapters/outbound`만 명시한다.
+2. TypeScript/feature migration과 함께 `adapters/inbound/react`와
+   `adapters/outbound`로 재구성한다.
+
+이 저장소는 input API 부재와 flat contracts 문제도 함께 고쳐야 하므로 두 번째
+구조가 장기적으로 더 명확하다. 단, 대규모 rename 자체를 기능 개선으로 세지 말고
+architecture gate와 수직 reference feature가 먼저 또는 같은 브랜치에서
+증명되어야 한다.
+
+### TypeScript로 바꾸는 것이 좋은가
+
+좋다. 특히 registry ID, Result/error union, port generic, route params/search,
+component variant를 컴파일 시점에 닫을 수 있다. 다만 일괄 rename은 권장하지
+않는다. tooling → core contracts → application ports/use cases → outbound →
+bootstrap → React TSX → tests 순서로 이동한다.
+
+### store 기본 설정이 필요한가
+
+상태 전략은 기본 제공해야 하지만 범용 global store dependency는 필수로 넣지
+않는다.
+
+- local interaction: `useState`/`useReducer`
+- shareable navigation state: URL
+- server state: TanStack Query
+- form state: form facade
+- low-frequency cross-cutting state: context 또는 typed external store
+- complex cross-feature workflow: Zustand/Redux Toolkit/state machine 중 선택
+- persistence: `StoragePort`
+
+서버 데이터를 global store에 복사하지 않는 규칙이 중요하다.
+[TanStack Query](https://tanstack.com/query/latest/docs/framework/react/overview),
+[Redux Toolkit](https://redux-toolkit.js.org/introduction/getting-started),
+[Zustand](https://zustand.docs.pmnd.rs/)의 역할은 서로 같지 않다.
+
+### retry, API client, logger, token manager, error, validation은 어디에 있는가
+
+- retry: `src/adapters/http/retry-policy.js`, 부분 준비
+- API client: `src/adapters/http/client.js`, 부분 준비
+- logger: `DiagnosticsPort`로 telemetry와 분리해 구현. closed event/level,
+  allowlist와 bounded/no-op adapter 제공
+- token manager: 의도적으로 없음. opaque external auth owner가 credential을 소유
+- error: `src/contracts/errors.js`와 HTTP normalization, 부분 준비
+- validation: runtime/API Zod는 존재, route/form/domain 분리는 미완성
+
+token manager를 기본으로 추가하지 않는 이유는 token lifecycle이 인증 방식마다
+다르고 localStorage token을 일반 해법으로 만들면 보안 위험이 커지기 때문이다.
+BFF HttpOnly cookie 또는 OIDC/Auth SDK가 credential을 소유하도록 두고, SPA
+memory token이 필요한 프로젝트만 auth adapter를 추가한다.
+
+### Lucide React를 쓰면 디자인 시스템이 되는가
+
+아니다. [Lucide React](https://lucide.dev/guide/packages/lucide-react)는
+tree-shakable SVG icon source로 적절하지만 select, dialog, menu, focus management
+같은 UI behavior는 제공하지 않는다. Lucide는 local icon facade 뒤에 두고,
+복잡한 interaction은 [Radix Primitives](https://www.radix-ui.com/primitives/docs/overview/introduction)
+또는 React Aria 계열과 같은 headless primitive를 owned wrapper 뒤에서 선택한다.
+
+### 테스트는 현재 어떤 상태인가
+
+테스트 도구 구성은 강한 편이다. 다만 다음이 빠져 있다.
+
+- TS source와 test 전체 typecheck
+- 실제 composition root부터 page까지의 통합
+- query/mutation controller와 optimistic rollback
+- route registry/runtime map 정합성은 RP-04에서 unit, component, negative
+  registry/type fixture와 built artifact 검증으로 구현됨
+- runtime timeout/retry와 path/query/parsed body
+- shared MSW scenario catalog
+- isolated component stories와 interaction test
+- stable-environment visual regression
+- built `dist` 대상 release E2E
+- 위험 기반 coverage gate
+
+### 라우팅 전략은 무엇이 적절한가
+
+현재 client-only clean architecture와 TanStack Query 조합은 유지하되, 목표
+skeleton은 React Router Data Mode의 route object, blocker, scroll restoration,
+route error 경계를 사용한다. 서버 상태의 소유자는 계속 application input과
+TanStack Query이며 loader/action이 같은 데이터를 별도로 요청하지 않는다.
+[React Router 공식 mode 설명](https://reactrouter.com/start/modes)에 따라
+Framework Mode는 SSR/static generation, route module, framework-owned data
+loading을 실제 요구할 때만 선택한다.
+
+### 바로 쓸 수 있는 디자인 패턴은 무엇을 제공해야 하는가
+
+패턴 이름만 나열하지 않고 다음 executable blueprint를 제공해야 한다.
+
+- page controller: route/form event를 application input으로 변환
+- query/mutation adapter: server state lifecycle을 React에 연결
+- command/query use case: 읽기와 상태 변경 의도를 분리
+- gateway: application이 외부 데이터 소유자를 추상화
+- mapper/anti-corruption layer: transport DTO를 core model로 변환
+- Result + failure mapper: throw와 사용자 메시지 경계를 통제
+- strategy: retry, cache, auth recovery, feature flag 정책 교체
+- observer/external store: session/theme/realtime 구독
+- state machine: 복잡한 workflow에만 선택적으로 사용
+- compound component/headless wrapper: 접근 가능한 복합 UI를 소유
+- page template: layout과 상태 표면을 데이터 소유권에서 분리
+
+## 7. 실전 투입 준비 완료 기준
+
+막연한 백분율 대신 아래 조건을 모두 자동 또는 명시적 검토로 확인한다.
+
+1. reference feature가 route → controller → input use case → output gateway →
+   adapter → mapper → query cache → UI 상태 표면을 통과한다.
+2. application input API 외에는 UI에서 outbound dependency에 접근할 수 없다.
+3. TypeScript source와 tests가 strict 검사되고 JS 우회 경로가 없다.
+4. HTTP path/query/body/auth/timeout/retry/cancel/decode 실패가 계약 테스트된다.
+5. typed route registry와 runtime map이 양방향 완전성을 가진다.
+6. list/detail/form/status page template과 form error 정책이 준비돼 있다.
+7. 디자인 시스템 primitive/pattern이 isolated workshop, interaction, a11y,
+   visual test를 가진다.
+8. sample/reference feature 전체 삭제 후 typecheck/test/build가 통과한다.
+9. optional adapter는 설치 조건, 보안 경계, 실패 정책, 테스트 recipe가 있다.
+10. 새 feature 추가 문서가 파일 경로, 금지 의존, 실패 상태, 테스트, 검증 명령까지
+    안내한다.
+
+이 기준은 배포 provider, 실제 인증 tenant, 운영 telemetry vendor, production field
+data 같은 프로젝트별 외부 작업을 포함하지 않는다.
+
+## 8. 관련 상세 문서
+
+- [프론트 포트·어댑터와 기능 경계](./frontend-ports-adapters-and-boundaries.md)
+- [TypeScript·상태·데이터 흐름](./typescript-state-and-data-flow.md)
+- [라우팅·페이지·재사용 패턴](./routing-pages-and-patterns.md)
+- [프론트 플랫폼 구현 로드맵](./frontend-platform-implementation-roadmap.md)
+- [디자인 시스템 플랫폼](../styling/design-system-platform.md)
+- [프론트 플랫폼 테스트 전략](../testing/frontend-platform-testing-strategy.md)

docs/architecture/layers.md

@@ -22,6 +22,14 @@ The following edges are forbidden:
 `bootstrap` contains composition only. Business rules and page-specific
 orchestration belong to domain/application.
 
+This table is the current coarse-grained rule. The
+[ports, adapters, and feature-boundary target](./frontend-ports-adapters-and-boundaries.md)
+defines the missing application input boundary, explains that `presentation`
+acts as the inbound adapter, and separates current outbound adapters from
+project-selected capabilities. The
+[platform capability review](./frontend-platform-capability-review.md) records
+where the current composition still bypasses this intended rule.
+
 Architecture reports use this shape:
 
 ```json

docs/architecture/overview.md

@@ -0,0 +1,61 @@
+# Architecture overview
+
+This Mermaid view is a repository-local implementation projection. The
+`PASS_SCOPED` reviewer evidence applies to the canonical draw.io diagram named
+in `review-ledger.json`, not automatically to edits in this file.
+
+```mermaid
+flowchart LR
+  Bootstrap[bootstrap / composition root] --> Presentation[presentation]
+  Bootstrap --> Adapters[adapters]
+  Presentation --> Shell[app shell and route surfaces]
+  Shell --> Providers[session and theme providers]
+  Presentation --> Application[application]
+  Adapters --> Application
+  Application --> Domain[domain]
+  Contracts[contract registries] --> Bootstrap
+  Contracts --> Adapters
+  Contracts --> Presentation
+```
+
+The intended dependency rule points inward: presentation calls application use
+cases, adapters implement application ports, and only the composition root
+selects concrete adapters. Contract registries are the intended named source
+for routes, API operations, environment values, storage keys, errors, queries,
+telemetry, and release tokens. The platform review below records where the
+current runtime still bypasses that target or duplicates registry metadata.
+
+In ports-and-adapters terms, `presentation` is the current inbound adapter and
+`adapters` contains the current outbound implementations. The target design
+makes this role explicit, introduces application input ports, and prevents the
+React tree from receiving raw outbound dependencies:
+
+```mermaid
+flowchart LR
+  Driver[User, route, browser event] --> Inbound[React inbound adapter]
+  Inbound --> Input[Application input API]
+  Input --> UseCase[Use cases]
+  UseCase --> Output[Application output ports]
+  Output --> Outbound[HTTP, auth, storage, query, telemetry adapters]
+  Bootstrap2[Composition root] -. selects and injects .-> Input
+  Bootstrap2 -. selects and injects .-> Outbound
+```
+
+The current executable route tree is mounted only after runtime configuration
+and release-manifest coherence pass. It receives the composed query client,
+credential-opaque session port, storage port, telemetry port, and immutable
+build ID. Generic starter pages do not depend on the removable reference
+feature.
+
+This describes the current starter composition, not the completed target. The
+capability review found that raw outbound capabilities still reach the React
+tree, the composed application facade is not yet its entry point, and several
+route, HTTP, recovery, telemetry, and reference-feature removal contracts are only
+partially connected. Use the following documents for the evidence and migration
+plan:
+
+- [Frontend platform capability review](./frontend-platform-capability-review.md)
+- [Frontend ports, adapters, and boundaries](./frontend-ports-adapters-and-boundaries.md)
+- [TypeScript, state, and data flow](./typescript-state-and-data-flow.md)
+- [Routing, pages, and patterns](./routing-pages-and-patterns.md)
+- [Frontend platform implementation roadmap](./frontend-platform-implementation-roadmap.md)

docs/architecture/review-evidence.md

@@ -0,0 +1,22 @@
+# Imported scoped diagram review evidence
+
+This ledger entry consumes the canonical evidence already recorded by the
+`ca-skeleton-frontend-operational-contract` project note. It does not claim
+review of the repository-local Mermaid projections or of the complete
+production deployment topology.
+
+- Reviewer: `wiki-diagram-reviewer`
+- Standard: `rules/diagram-standards.md` v2
+- Canonical report:
+  `docs/superpowers/specs/2026-07-18-ca-skeleton-frontend-operational-contract-review/diagram-review.md`
+- Canonical report SHA-256:
+  `b4d2a35e4f07e176717786408f98dab5cee1047f77f6ff61f5faeddfccd78a29`
+
+| Canonical diagram | SHA-256 | Score | Verdict | Reviewed scope |
+| --- | --- | ---: | --- | --- |
+| `raw/diagrams/ca-skeleton-frontend/architecture-overview-2026-07-18.drawio` | `c0ae56c9c964c5c6e698ab7dcc91736b9b811b2b834381817905db81c4230ba0` | 100 | PASS | Clean Architecture compile-time dependency ownership |
+| `raw/diagrams/ca-skeleton-frontend/architecture-deployment-2026-07-18.drawio` | `9a654326fb840ddf24b832221ff7eec4b8fadd9f87ad84174fccfa3bfcd1a25b` | 100 | PASS | immutable static assets and mutable `/config.json` delivery |
+
+The canonical report explicitly limits this `PASS_SCOPED`: it does not verify
+the complete release/rollback topology, the implementation topology, or live
+hosting state.

docs/architecture/review-ledger.json

@@ -0,0 +1,29 @@
+{
+  "schemaVersion": 1,
+  "status": "PASS_SCOPED",
+  "reviewer": "wiki-diagram-reviewer",
+  "standard": "rules/diagram-standards.md v2",
+  "evidenceReport": {
+    "repoPath": "docs/architecture/review-evidence.md",
+    "canonicalPath": "docs/superpowers/specs/2026-07-18-ca-skeleton-frontend-operational-contract-review/diagram-review.md",
+    "canonicalSha256": "b4d2a35e4f07e176717786408f98dab5cee1047f77f6ff61f5faeddfccd78a29"
+  },
+  "reviews": {
+    "overview": {
+      "sourcePath": "raw/diagrams/ca-skeleton-frontend/architecture-overview-2026-07-18.drawio",
+      "sha256": "c0ae56c9c964c5c6e698ab7dcc91736b9b811b2b834381817905db81c4230ba0",
+      "score": 100,
+      "verdict": "PASS",
+      "thresholdSatisfied": true,
+      "scope": "Clean Architecture compile-time dependency ownership"
+    },
+    "staticDelivery": {
+      "sourcePath": "raw/diagrams/ca-skeleton-frontend/architecture-deployment-2026-07-18.drawio",
+      "sha256": "9a654326fb840ddf24b832221ff7eec4b8fadd9f87ad84174fccfa3bfcd1a25b",
+      "score": 100,
+      "verdict": "PASS",
+      "thresholdSatisfied": true,
+      "scope": "immutable static assets and mutable /config.json delivery"
+    }
+  }
+}

docs/architecture/routing-pages-and-patterns.md

@@ -0,0 +1,505 @@
+# 라우팅, 페이지 템플릿, 재사용 패턴
+
+## 1. 목적
+
+이 문서는 도메인과 무관하게 다음을 바로 구현할 수 있는 기준을 제공한다.
+
+- typed route와 안전한 URL
+- session, permission, feature flag guard
+- lazy chunk의 loading/error/recovery
+- route 이동 시 focus, scroll, 취소, dirty form 처리
+- list, detail, form, status 등 공통 page template
+- page controller와 application input use case의 연결
+- 프론트엔드에서 반복 사용하는 설계 패턴
+
+## 2. 현재 상태와 구현 기준
+
+RP-04 이후 route runtime과 RP-06 page/form platform에는 다음 장점이 있다.
+
+- route registry가 path와 access policy를 소유한다.
+- contract에서 Data Router route object와 navigation을 생성한다.
+- runtime map이 route component를 lazy import하고 codec을 연결한다.
+- 앱 셸과 보호 route, not-found surface가 있다.
+- route heading focus와 비동기/render error boundary가 있다.
+- redirect loop와 chunk recovery가 bounded production call graph에 연결돼 있다.
+- `src/presentation/templates`가 standard/collection/detail/form/status slot,
+  landmark와 responsive layout을 제공한다.
+- `src/presentation/forms`가 첫 오류 focus, error summary, 422 mapping,
+  duplicate submit과 dirty route blocker를 소유한다.
+- reference feature의 list/detail/create/status route가 네 template variation을
+  production composition에서 실행한다.
+
+platform route 계약, `src/features/installed-feature-contracts.js`,
+`src/features/installed-feature-runtimes.tsx`의 완전성은 TypeScript와 registry
+negative fixture가 함께 검사한다. params/search codec, loading/error surface,
+access, title, navigation, chunk ID는
+`src/presentation/routes/app-router.tsx`에서 모두 소비된다. built Vite
+manifest의 dynamic entry는 release manifest route chunk map과 검증되며,
+`ChunkRecoveryBoundary`는 일반 render error와 chunk rejection을 분리한다.
+
+template는 데이터를 가져오지 않는다. reference page controller가 route input과
+application input을 query/form facade에 연결하고, template에는 render할 slot과
+안전한 callback만 전달한다. 이 분리는
+`page-templates-own-layout-only` dependency rule과 forbidden import fixture가
+검증한다.
+
+## 3. React Router mode 결정
+
+[React Router 공식 mode 설명](https://reactrouter.com/start/modes)과
+[Data Mode custom setup](https://reactrouter.com/start/data/custom)은
+Declarative, Data, Framework Mode를 구분한다.
+
+저장소에는 현재 React Router `7.18.1`이 고정돼 있다. 구현 브랜치는 공식 문서의
+동일 버전 API를 기준으로 하고 router version upgrade를 Data Mode 구조 변경과
+같은 브랜치에 섞지 않는다. 위 공식 링크의 기본 표시 버전이 바뀌면 version
+selector를 `7.18.1`로 맞춰 확인한다.
+
+| mode | 선택 조건 | 이 저장소에서의 판단 |
+| --- | --- | --- |
+| Declarative | React composition과 외부 data layer가 route data를 소유 | RP-04 이전 기준선 |
+| Data | route object, blocker, scroll restoration, pending/navigation state가 필요 | VD-03으로 채택하고 RP-04에서 구현 |
+| Framework | route module, type-safe href, code splitting, SSR/static 전략을 framework가 소유 | client-only skeleton 기본값으로는 범위가 큼 |
+
+채택한 결정:
+
+- client-only SPA와 TanStack Query/application use case를 유지한다.
+- `createBrowserRouter`와 `RouterProvider` 기반 Data Mode를 사용한다.
+- Data Mode를 선택하는 이유는 route object, navigation blocker, scroll
+  restoration, route error 경계를 일관되게 소유하기 위해서다. loader/action으로
+  서버 상태를 다시 소유하기 위해서가 아니다.
+- loader/action을 추가할 때는 TanStack Query/application input을 prefetch하거나
+  호출하는 한 가지 소유 경로만 사용한다.
+- 같은 데이터를 route loader와 TanStack Query가 각각 가져오지 않는다.
+- SSR/static generation을 선택하기 전에는 Framework Mode를 기본값으로 만들지
+  않는다.
+
+결정 근거와 rollback 경계는
+`docs/architecture/decisions/VD-03-react-router-data-mode.md`에 고정한다.
+Data Mode를 사용할 수 없는 프로젝트만 별도 ADR과
+`NavigationLifecycleAdapter`를 구현한다.
+
+## 4. route 계약과 runtime map
+
+### 4.1 두 종류의 레지스트리
+
+직렬화 가능한 contract와 React implementation을 분리한다.
+
+```ts
+export const routeContracts = {
+  home: {
+    id: "home",
+    path: "/",
+    access: "public",
+    navigation: "primary",
+    titleKey: "route.home.title",
+    loadingSurface: "page",
+    errorSurface: "page",
+    chunkId: "home",
+  },
+  resourceDetail: {
+    id: "resourceDetail",
+    path: "/examples/resources/:resourceId",
+    access: "authenticated",
+    navigation: "hidden",
+    titleKey: "route.resourceDetail.title",
+    loadingSurface: "detail",
+    errorSurface: "detail",
+    chunkId: "reference-resource-detail",
+  },
+} as const satisfies RouteContractRegistry;
+```
+
+```tsx
+export const routeRuntime = {
+  home: {
+    Component: lazy(() => import("../pages/home-page")),
+    paramsCodec: emptyParamsCodec,
+    searchCodec: emptySearchCodec,
+  },
+  resourceDetail: {
+    Component: lazy(() => import("../features/resources/resource-detail-page")),
+    paramsCodec: resourceDetailParamsCodec,
+    searchCodec: resourceDetailSearchCodec,
+  },
+} satisfies Record<RouteId, RouteRuntime>;
+```
+
+요구 사항:
+
+- contract key와 `id`가 다르면 typecheck 실패
+- contract에는 함수, component, schema instance처럼 직렬화 불가능한 값을 넣지 않음
+- runtime map에는 실제 lazy component와 codec/guard만 둠
+- contract의 모든 route가 runtime에 있고 runtime의 모든 key가 contract에 있음
+- navigation은 contract에서 파생
+- build chunk manifest와 `chunkId` 대응을 검증
+- public runtime config나 server가 route component 이름을 임의 지정할 수 없음
+
+### 4.2 params와 search codec
+
+URL은 외부 입력이다. page에서 `useParams()` 결과를 cast하지 않는다.
+
+```ts
+const resourceDetailParamsSchema = z.object({
+  resourceId: z.string().trim().min(1).max(100),
+});
+
+const resourceListSearchSchema = z.object({
+  q: z.string().trim().max(100).catch(""),
+  page: z.coerce.number().int().min(1).catch(1),
+  sort: z.enum(["updated-desc", "name-asc"]).catch("updated-desc"),
+});
+```
+
+path params와 search params는 입력 형태와 serialization 규칙이 다르므로 같은
+interface로 뭉치지 않는다. 각각 parse와 serialize를 제공한다.
+
+```ts
+interface PathParamsCodec<T> {
+  parse(
+    input: Readonly<Record<string, string | undefined>>,
+  ): Result<T, RouteInputFailure>;
+  serialize(value: T): Readonly<Record<string, string>>;
+}
+
+interface SearchParamsCodec<T> {
+  parse(input: URLSearchParams): Result<T, RouteInputFailure>;
+  serialize(value: T): URLSearchParams;
+}
+```
+
+규칙:
+
+- route input parse 실패와 backend 404를 구분한다.
+- 알 수 없는 search key를 보존할지 제거할지 route별로 선언한다.
+- default value를 URL에 항상 쓸지 생략할지 codec이 결정한다.
+- array/date/boolean encoding을 feature마다 다르게 만들지 않는다.
+- navigation link도 codec 기반 builder를 사용한다.
+- query key에는 parsed value만 사용한다.
+- 검색어·식별자를 telemetry에 기록하기 전에 sensitivity policy를 적용한다.
+
+### 4.3 route object 생성
+
+하나의 factory가 다음을 조합한다.
+
+```text
+route contract
+  + runtime component/codecs
+  + access guard
+  + feature flag guard
+  + suspense surface
+  + render/chunk error surface
+  + title/focus/scroll behavior
+  -> executable route object/tree
+```
+
+JSX에서 route별 `<Route>`를 다시 나열하지 않는다. nested layout이 필요한 경우
+contract에 parent ID를 두고 cycle/orphan/duplicate path를 registry gate에서
+검사한다.
+
+## 5. guard와 권한
+
+### 5.1 guard 순서
+
+권장 순서:
+
+1. runtime/bootstrap readiness
+2. route 존재와 URL parse
+3. feature flag
+4. session readiness
+5. authentication
+6. coarse client permission hint
+7. route component
+8. server authorization result
+
+client guard는 UX 최적화일 뿐 보안 경계가 아니다. API/BFF가 항상 최종 권한을
+검사한다.
+
+### 5.2 guard 결과
+
+```ts
+type GuardDecision =
+  | { kind: "allow" }
+  | { kind: "redirect"; to: SafeLocation; reason: RedirectReason }
+  | { kind: "render"; surface: "auth-required" | "forbidden" | "not-found" };
+```
+
+- redirect에는 origin route와 bounded return URL을 사용한다.
+- 외부 redirect는 allowlist를 거친다.
+- 동일한 route 쌍을 반복하는 redirect loop를 차단한다.
+- session이 아직 resolving이면 forbidden으로 단정하지 않는다.
+- server가 403을 반환하면 client claim을 신뢰해 화면을 계속 보여 주지 않는다.
+
+## 6. navigation lifecycle
+
+### 6.1 loading
+
+loading surface를 route metadata에 연결한다.
+
+| surface | 사용 |
+| --- | --- |
+| shell | 초기 앱 셸 진입 |
+| page | 새로운 전체 페이지 |
+| collection | table/list 구조 유지 |
+| detail | metadata/content 구조 유지 |
+| form | 필드 layout 구조 유지 |
+| inline | 부분 action |
+
+cached data가 있으면 full-page skeleton으로 교체하지 않고 refreshing indicator를
+사용한다. `prefers-reduced-motion`에서 skeleton animation을 줄인다.
+
+### 6.2 error와 lazy chunk recovery
+
+route error boundary는 다음을 구분한다.
+
+- render/programmer error
+- dynamic import/chunk load error
+- application `AppFailure`
+- URL parse failure
+- not found
+
+chunk recovery 순서:
+
+1. 현재 build ID와 release manifest를 확인한다.
+2. 새 manifest가 확인되고 같은 build에 대해 reload하지 않았다면 한 번만 reload한다.
+3. 같은 failure가 반복되면 reload loop를 막는다.
+4. 안전한 support surface와 trace/build ID를 표시한다.
+5. recovery 결과를 redacted diagnostics에 기록한다.
+
+custom fallback을 넘겨 retry/reset 기능을 잃지 않게 한다. boundary는
+`location.key` 또는 route ID가 바뀌면 적절히 reset된다.
+
+### 6.3 focus와 scroll
+
+- route 성공 후 `main`의 page heading에 programmatic focus
+- mouse 사용자가 불필요한 focus ring을 보지 않게 할 수는 있지만 keyboard focus
+  indication을 전역으로 제거하지 않음
+- modal/drawer가 닫히면 opener에 focus 복원
+- backward/forward navigation은 저장한 scroll 복원
+- 새 primary route는 top으로 이동
+- hash target은 fixed header offset과 focus 가능 여부를 처리
+- screen reader용 route title/live announcement는 중복 발표를 피함
+
+### 6.4 취소와 dirty form
+
+- route 이동 시 진행 중 query signal을 취소한다.
+- mutation은 취소 안전성이 명확할 때만 취소한다.
+- dirty form blocker는 browser unload와 in-app navigation을 구분한다.
+- 성공 저장 후 blocker를 해제한 다음 이동한다.
+- autosave가 있는 form은 pending/failed 상태를 별도로 알린다.
+- confirm dialog는 공통 accessible primitive를 사용한다.
+
+## 7. 페이지 템플릿
+
+template은 데이터를 가져오거나 application을 호출하지 않는다. 슬롯, landmark,
+focus target, responsive layout, 상태 위치만 소유한다.
+
+### 7.1 `StandardPageTemplate`
+
+슬롯:
+
+- breadcrumb 또는 back link
+- title, description, status badge
+- primary/secondary actions
+- notices
+- content
+- contextual aside
+
+작은 화면에서 action wrapping 순서와 heading hierarchy를 보장한다.
+
+### 7.2 `CollectionPageTemplate`
+
+슬롯과 상태:
+
+- title/actions
+- search/filter/sort toolbar
+- active filter summary와 reset
+- result count
+- table/list/card view
+- pagination 또는 load-more
+- initial loading, refreshing, empty-first-use, empty-filtered, error
+- bulk selection/action
+
+URL이 filter, sort, page를 소유한다. template은 query 상태를 직접 읽지 않는다.
+
+### 7.3 `DetailPageTemplate`
+
+- breadcrumb/back
+- title/status/actions
+- summary metadata
+- main sections
+- related/context aside
+- loading/not-found/forbidden/error
+- destructive action confirmation 위치
+
+식별자가 바뀔 때 이전 entity 내용과 새 loading 상태를 혼동하지 않게 key/reset
+정책을 명시한다.
+
+### 7.4 `FormPageTemplate`
+
+- title/description
+- error summary
+- field groups
+- optional aside/help
+- sticky 또는 normal action bar
+- submit/cancel
+- submitting/saved/conflict/unavailable
+- dirty navigation confirmation
+
+template은 특정 form vendor를 import하지 않는다.
+
+### 7.5 `StatusPageTemplate`
+
+다음 변형을 제공한다.
+
+- unauthenticated
+- forbidden
+- not found
+- unavailable
+- offline
+- maintenance
+- unexpected
+
+각 변형은 heading, 짧은 설명, 안전한 primary/secondary action, 선택적 trace ID를
+갖는다. raw stack/response를 표시하지 않는다.
+
+### 7.6 선택 template
+
+다음은 project 필요가 있을 때 추가한다.
+
+- `SettingsPageTemplate`
+- `DashboardGridTemplate`
+- `SplitPaneTemplate`
+- `WizardTemplate`
+- `FullScreenTaskTemplate`
+
+## 8. page controller 패턴
+
+page를 세 부분으로 나눈다.
+
+```text
+route adapter
+  parses URL and guard context
+      ↓
+controller hook
+  invokes application query/mutation and maps UI events
+      ↓
+page view
+  renders template and design-system components
+```
+
+예:
+
+```tsx
+export function ResourceListRoute() {
+  const input = useRouteInput(resourceListRoute);
+  if (!input.ok) return <InvalidRouteSurface failure={input.error} />;
+
+  return <ResourceListController input={input.value} />;
+}
+
+function ResourceListController({ input }: ResourceListControllerProps) {
+  const controller = useResourceListController(input);
+  return <ResourceListPage controller={controller} />;
+}
+```
+
+route parse boundary와 controller component를 분리하므로 controller hook은
+조건부로 호출되지 않는다.
+
+controller가 소유하는 것:
+
+- parsed route input을 application input으로 변환
+- query/mutation state
+- pagination/filter/navigation event
+- retry/refresh/action callbacks
+- view model projection
+
+view가 소유하는 것:
+
+- semantic markup
+- template/component 조립
+- focus target
+- 사용자의 local-only interaction
+
+controller가 소유하지 않는 것:
+
+- HTTP URL 조립
+- credential
+- transport DTO parse
+- 도메인 invariant
+- raw vendor SDK
+
+## 9. 권장 패턴 카탈로그
+
+| 패턴 | 적용 위치 | 쓰는 이유 | 오용 |
+| --- | --- | --- | --- |
+| Ports and Adapters | application 외부 경계 | 정책과 기술 교체 분리 | 모든 작은 UI library에 port 생성 |
+| Command/Query | application input | 읽기/변경 의도와 정책 분리 | CQRS 인프라를 필요 없이 도입 |
+| Gateway | output port | 외부 데이터 capability 표현 | `get/post` 범용 HTTP를 application에 노출 |
+| Anti-Corruption Mapper | outbound feature adapter | DTO 변화가 core로 전파되지 않게 함 | 단순 object spread로 타입만 바꿈 |
+| Result | 예상 실패 | 실패 종류와 처리 경로를 닫음 | programmer error까지 모두 Result로 숨김 |
+| Controller/View | inbound React | data lifecycle과 markup 분리 | 거대한 hook 하나에 모든 feature 로직 집중 |
+| Strategy | retry/cache/auth recovery | 정책 교체와 테스트 가능성 | 설정 한 줄도 interface로 과도 추상화 |
+| Observer/External Store | session/theme/realtime | React 외부 소유 상태 구독 | server state를 다시 external store에 복제 |
+| State Machine | 복잡한 workflow | 유효 전이와 보상 명시 | 단순 modal open에 도입 |
+| Headless/Compound Component | 복합 UI | behavior와 style/slot 분리 | vendor primitive를 제품 전역에 직접 노출 |
+| Adapter Facade | icon/form/i18n vendor | React inbound 내부 vendor 교체 경계 | application port로 승격 |
+| Page Template | 반복 layout/state | 접근성과 반응형 구조 재사용 | data fetching을 template에 포함 |
+| Registry + Runtime Map | route/operation/event | 선언과 실행 완전성 | 모든 설정을 하나의 거대 전역 파일에 집중 |
+
+RP-08 이후 route contract의 `title`/`navigation` 필드는 fallback metadata이며
+실제 document title, navigation, loading/error/access surface는
+`route.<ROUTE_ID>.title|navigation` typed catalog key를 해석한다. route params,
+search, backend message를 translation key로 조립하지 않는다. locale 변경은
+현재 route를 재요청하거나 query key를 바꾸지 않고 document title과 화면 copy만
+다시 렌더링한다.
+
+패턴은 추상화 파일만 만든 것으로 완료되지 않는다. reference usage, negative
+architecture test, 실패 상태 test가 있어야 제공된 패턴으로 본다.
+
+## 10. 새 route/page 추가 recipe
+
+1. feature public 경계와 route ID를 정한다.
+2. serializable route contract를 등록한다.
+3. params/search Zod schema와 bidirectional codec을 작성한다.
+4. safe URL builder를 export한다.
+5. lazy page module과 runtime map entry를 추가한다.
+6. session/permission/flag guard를 선언한다.
+7. 적절한 page template을 선택한다.
+8. controller hook을 application input API에 연결한다.
+9. loading, empty, refreshing, error, auth, forbidden, not-found를 결정한다.
+10. title/message key, focus, scroll, chunk ID를 연결한다.
+11. 다음 검증을 추가한다.
+    - contract/runtime map type completeness
+    - codec round-trip/property cases
+    - guard decision unit
+    - page component state
+    - query/mutation integration
+    - keyboard/focus/axe
+    - direct URL, back/forward, refresh E2E
+    - chunk failure recovery가 필요한 route의 E2E
+12. registry, type, architecture, component, integration, E2E gate를 실행한다.
+
+## 11. 금지 패턴
+
+- page 안에서 raw `fetch`, storage, auth SDK, telemetry SDK 호출
+- `useParams()`/`URLSearchParams` 값을 cast만 하고 사용
+- route contract와 JSX route tree를 각각 수동 관리
+- protected route를 server authorization 대체 수단으로 취급
+- 모든 실패를 redirect 또는 full-page error로 처리
+- query data가 있는데 background error 때문에 내용을 제거
+- chunk load error에서 제한 없는 `location.reload`
+- route heading focus outline을 CSS로 무조건 제거
+- template이 data fetching 또는 feature-specific copy를 소유
+- generic `BasePage` prop 하나에 모든 layout variation을 boolean으로 추가
+
+## 12. 완료 기준
+
+- 모든 route ID가 contract와 runtime map에서 compile-time 완전성을 가진다.
+- params/search parse와 URL serialize가 같은 codec을 사용한다.
+- route metadata가 loading/error/chunk/title/navigation 행동에 실제 연결된다.
+- redirect와 chunk reload loop가 차단된다.
+- route 이동 시 query 취소, focus, scroll, dirty policy가 검증된다.
+- collection/detail/form/status reference page가 template을 사용한다.
+- page view가 application input 외의 외부 capability를 직접 호출하지 않는다.
+- 새 route recipe와 테스트만으로 별도 라우터 내부 지식 없이 기능을 추가할 수 있다.

docs/architecture/starter-experience.md

@@ -0,0 +1,79 @@
+# Starter experience contract
+
+The repository provides a runnable, domain-neutral application rather than
+only infrastructure contracts. The starter experience is intentionally
+replaceable at the page level while the shell, providers, boundaries,
+primitives, and state surfaces remain reusable.
+
+## Runtime composition
+
+```text
+validated config + coherent release manifest
+  -> concrete adapters
+  -> QueryClientProvider
+  -> ApplicationProvider
+  -> RouterProvider
+  -> ThemeProvider
+  -> SessionProvider
+  -> AppShell
+  -> lazy route boundary
+```
+
+Boot stops before product mount when configuration or release coherence fails.
+Each lazy page renders inside Suspense and a telemetry-aware route boundary.
+Route changes move focus to the new page heading; the skip link and landmarks
+remain stable in the shell.
+
+## Registered routes
+
+| ID | Path | Access | Surface |
+| --- | --- | --- | --- |
+| `APP_HOME` | `/` | public | readiness dashboard |
+| `EXAMPLES_UI` | `/examples/ui` | public | interactive primitives and tokens |
+| `EXAMPLES_STATES` | `/examples/states` | public | async and access state matrix |
+| `EXAMPLES_AUTH` | `/examples/auth` | public | session integration controls |
+| `REFERENCE_RESOURCE_LIST` | `/examples/reference-resources` | integration-defined | removable vertical slice |
+| `NOT_FOUND` | `*` | public | safe navigation recovery |
+
+Navigation labels and order come from `ROUTE_REGISTRY`; the sidebar does not
+maintain a second route list. The client access decision never claims to be
+authorization.
+
+## Authentication seam
+
+The session port exposes state subscription, sign-in start, sign-out,
+credential attachment, recovery, and unauthenticated notification. Credentials
+remain opaque to the application and presentation layers.
+
+- `demo`: local/development-only state transition with no credentials
+- `external`: delegates to `globalThis.__CA_FRONTEND_AUTH_OWNER__`
+- missing/invalid external owner: fails closed as `integration-failed`
+
+An external owner implements `readState`, `subscribe`, `beginSignIn`,
+`signOut`, `attachCredential`, `recoverSession`, and
+`notifyUnauthenticated`. It owns token acquisition and storage.
+
+## Extending the starter
+
+The steps below describe the current extension path. New platform work should follow
+[routing, page templates, and reusable patterns](./routing-pages-and-patterns.md)
+and the
+[TypeScript, state, and data-flow target](./typescript-state-and-data-flow.md)
+rather than adding another independent route or data-loading convention.
+
+1. Add a serializable contribution under the feature ownership boundary and
+   install it through `src/features/installed-feature-contracts.js`.
+2. Add the lazy component and route codecs through
+   `src/features/installed-feature-runtimes.tsx`.
+3. Compose feature application inputs and outbound gateways only through
+   `src/features/installed-feature-adapters.ts`.
+4. Use the semantic tokens, UI primitives, and state surfaces before adding a
+   project-specific variant.
+5. Add component behavior, all-engine E2E, automated axe, and signed manual
+   route evidence.
+6. Run `test:sample-removal` to prove the generic starter typechecks, passes
+   architecture/registry/tests/home smoke, and builds without the complete
+   reference feature.
+
+Theme preference is the public `COLOR_SCHEME` storage contract. Authentication
+tokens and other secrets remain forbidden storage keys.

docs/architecture/static-delivery.md

@@ -0,0 +1,25 @@
+# Static asset and runtime-config delivery
+
+This Mermaid view is a repository-local implementation projection. The
+`PASS_SCOPED` reviewer evidence applies only to the canonical static-delivery
+draw.io scope recorded in `review-ledger.json`.
+
+```mermaid
+sequenceDiagram
+  participant CI
+  participant ImmutableRelease
+  participant ActivePointer
+  participant Browser
+  CI->>ImmutableRelease: upload hashed assets
+  CI->>ImmutableRelease: upload release manifest
+  CI->>ImmutableRelease: upload runtime config
+  CI->>ImmutableRelease: probe asset reachability
+  CI->>ActivePointer: atomically switch HTML
+  Browser->>ActivePointer: fetch revalidated HTML
+  Browser->>ImmutableRelease: fetch no-store config and manifest
+  Browser->>ImmutableRelease: fetch immutable hashed assets
+  CI->>Browser: boot, route, API, and reload-loop smoke
+```
+
+Rollback changes the active pointer only after confirming that the prior
+immutable release has a coherent HTML/assets/config/API/manifest tuple.

docs/architecture/typescript-state-and-data-flow.md

@@ -0,0 +1,622 @@
+# TypeScript, 상태 소유권, 데이터 흐름
+
+## 1. 목적
+
+이 문서는 다음 질문에 대한 저장소 표준을 정의한다.
+
+- JavaScript를 어떤 순서로 TypeScript로 전환하는가.
+- local, URL, server, form, global, persisted 상태를 어디에 둬야 하는가.
+- React 화면이 application use case와 TanStack Query를 어떻게 사용해야 하는가.
+- HTTP, retry, auth, error, validation, logging의 책임을 어떻게 나누는가.
+- 새 query, mutation, form을 추가할 때 어떤 파일과 테스트가 필요한가.
+
+이 문서는 목표 설계다. 현재 구현 상태는
+[프론트엔드 플랫폼 역량 재검토](./frontend-platform-capability-review.md)를 따른다.
+
+## 2. TypeScript 전환 원칙
+
+### 2.1 왜 전환하는가
+
+현재 `strict + allowJs + checkJs`는 JavaScript 상태에서 유용한 안전망이다. 그러나
+JSDoc cast가 늘어나면 다음 계약을 정확히 닫기 어렵다.
+
+- `RouteId`, `OperationId`, `ErrorCode`, `StorageKey`, `TelemetryEvent`
+- `Result<T, E>`와 discriminated failure union
+- use case input/output와 gateway generic
+- route별 params/search type
+- query key tuple
+- component variant와 slot prop
+- runtime registry의 key와 executable implementation의 완전성
+
+TypeScript 전환 목적은 확장자 변경이 아니라 이 계약을 컴파일 단계에서
+검증하는 것이다.
+
+### 2.2 전환 전에 고칠 도구
+
+다음 변경이 첫 브랜치에서 완료되기 전에는 source rename을 시작하지 않는다.
+
+1. ESLint가 `js`, `jsx`, `mjs`, `ts`, `tsx`, `mts`를 모두 검사한다.
+2. React Hooks 규칙을 추가하고 TypeScript/ESLint parser와 JSX accessibility
+   도구는 설치된 compiler/linter의 공식 peer 범위 안에서 선택한다.
+3. dependency-cruiser의 extension과 resolver가 TS/TSX를 포함한다.
+4. `scripts/check-registries.mjs`가 TS/TSX를 검색한다.
+5. `config/contracts/registry-governance.json`의 경로 갱신 절차를 만든다.
+6. Vite, Vitest, Playwright, scripts, source, tests를 각각 typecheck한다.
+7. invalid type fixture가 TS migration 후에도 “실패해야 통과”하는지 확인한다.
+8. architecture/security/registry gate가 TS fixture 위반을 실제로 잡는 negative test를
+   추가한다.
+
+권장 project 구성:
+
+```text
+tsconfig.base.json
+tsconfig.app.json
+tsconfig.node.json
+tsconfig.test.json
+tsconfig.json          # project references only
+```
+
+`tsconfig.base.json`의 초기 핵심 옵션:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noEmit": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "useUnknownInCatchVariables": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true
+  }
+}
+```
+
+실제 TypeScript 7/Vite 호환 옵션은 설치된 공식 문서와 빌드 결과를 기준으로
+확정한다. 옵션을 한꺼번에 켜서 수백 개 예외를 만들지 말고, 각 단계에서 새
+예외를 금지한다.
+
+현재 저장소의 VD-01 결정은
+[TypeScript 7과 ESLint 10의 점진적 전환 도구](./decisions/VD-01-typescript-lint-tooling.md)에
+기록돼 있다. app, Node scripts/config, tests는 각각 독립된 project로
+typecheck하며 JS에는 `checkJs`, TS에는 `strict`를 적용한다. TypeScript 7을
+아직 지원하지 않는 parser plugin을 강제 설치하지 않고 Babel parser는 lint
+syntax/import/security 검사, `tsc`는 type semantics를 소유한다.
+
+### 2.3 전환 순서
+
+| 단계 | 대상 | 이유 | 종료 조건 |
+| --- | --- | --- | --- |
+| 0 | lint/typecheck/scanner/architecture tooling | TS 코드가 검사를 우회하지 않게 함 | TS 위반 fixture가 각 게이트에서 실패 |
+| 1 | result, failure, ID, registry types | 이후 모든 계층의 언어가 됨 | stringly typed public ID 제거 |
+| 2 | application input/output ports와 use case | 중심 계약을 먼저 고정 | input/output compile fixture 통과 |
+| 3 | domain model과 mapper boundary | DTO와 core model 혼합 차단 | mapper contract test 통과 |
+| 4 | outbound adapters | 외부 `unknown`을 경계에서 좁힘 | HTTP/storage/auth failure type 통과 |
+| 5 | bootstrap/composition | 누락 dependency를 컴파일로 검출 | 실제 composition type test 통과 |
+| 6 | React providers/controllers/routes | typed application API 소비 | route/runtime map 완전성 검사 |
+| 7 | primitives/pages/templates | component API와 variant를 닫음 | stories/component tests typecheck |
+| 8 | tests/scripts/config | 우회 없는 전체 저장소 | source `allowJs` 제거 가능 |
+
+각 단계는 빌드 가능한 작은 커밋으로 유지한다. JavaScript와 TypeScript가 공존하는
+동안에는 [공식 JavaScript migration 가이드](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html)의
+점진적 방식을 사용한다.
+
+### 2.4 기본 type 계약
+
+다음 형태를 core application에 둔다.
+
+```ts
+export type Ok<T> = Readonly<{ ok: true; value: T }>;
+export type Err<E> = Readonly<{ ok: false; error: E }>;
+export type Result<T, E> = Ok<T> | Err<E>;
+
+export type AppFailure =
+  | Readonly<{ kind: "unauthenticated"; code: "AUTH_REQUIRED"; traceId?: string }>
+  | Readonly<{ kind: "forbidden"; code: "FORBIDDEN"; traceId?: string }>
+  | Readonly<{ kind: "not-found"; code: "NOT_FOUND"; traceId?: string }>
+  | Readonly<{ kind: "conflict"; code: "CONFLICT"; traceId?: string }>
+  | Readonly<{
+      kind: "validation";
+      code: "VALIDATION_FAILED";
+      fields: Readonly<Record<string, readonly string[]>>;
+      traceId?: string;
+    }>
+  | Readonly<{ kind: "rate-limited"; code: "RATE_LIMITED"; retryAt?: Date }>
+  | Readonly<{ kind: "unavailable"; code: "UNAVAILABLE"; retryable: boolean }>
+  | Readonly<{ kind: "unexpected"; code: "UNEXPECTED"; traceId?: string }>;
+```
+
+원칙:
+
+- adapter에서 받은 `unknown`은 adapter 경계에서 parse한다.
+- application은 `Response`, `AxiosError`, Zod 내부 오류 같은 vendor type을
+  노출하지 않는다.
+- UI copy는 failure에 저장하지 않고 message key mapper에서 결정한다.
+- 예상 가능한 실패는 `Result`; programmer bug와 render crash는 error boundary로
+  보낸다.
+- `as`, non-null assertion, `any`는 경계에서 근거가 있을 때만 사용하고 lint
+  예외에 사유를 기록한다.
+
+## 3. 상태 소유권
+
+### 3.1 상태 분류표
+
+상태를 만들기 전에 아래 순서로 소유자를 결정한다.
+
+| 질문 | 상태 종류 | 기본 도구 | 저장 위치 |
+| --- | --- | --- | --- |
+| 한 컴포넌트 상호작용에만 필요한가 | local UI | `useState`, `useReducer` | component/controller |
+| URL로 공유·복원되어야 하는가 | navigation | router params/search + codec | URL |
+| 서버가 진실의 원천인가 | server state | TanStack Query inbound adapter | Query cache |
+| 입력 중이고 제출 전인가 | form | local form facade | form controller |
+| 앱 전체에서 낮은 빈도로 바뀌는가 | cross-cutting | Context 또는 typed external store | provider/store |
+| 여러 feature의 복잡한 workflow인가 | client workflow | reducer, Zustand, Redux Toolkit, state machine | feature-owned store |
+| 새로고침 후 남아야 하는가 | persisted preference | `StoragePort` | versioned browser storage |
+| 인증 credential인가 | auth secret | external auth owner | SDK memory 또는 HttpOnly cookie |
+
+금지:
+
+- server response를 global client store에 복사하지 않는다.
+- URL에 있어야 할 filter/sort/page를 숨은 store에만 두지 않는다.
+- component 내부에 머물 수 있는 modal open 상태를 전역화하지 않는다.
+- access token을 localStorage, sessionStorage, 일반 Redux/Zustand store에 넣지
+  않는다.
+- 모든 상태를 추상화하는 범용 `StorePort`를 만들지 않는다.
+
+### 3.2 범용 store 선택 기준
+
+기본 skeleton에는 빈 Zustand/Redux store를 만들지 않는다. 실제 요구가 생기면
+다음 기준을 적용한다.
+
+| 조건 | 권장 |
+| --- | --- |
+| feature 한 곳의 단순 shared client state | feature reducer 또는 작은 Zustand store |
+| 여러 팀이 action/state 규약, devtools, middleware, audit를 공유 | Redux Toolkit |
+| 명시적 상태 전이, 병렬 상태, 취소/보상 workflow | state machine |
+| session/theme처럼 저빈도 cross-cutting | `useSyncExternalStore` 또는 Context |
+
+vendor를 선택하더라도 feature 외부에는 hook/facade만 export한다. 제품 코드가
+store instance의 `getState`와 `setState`를 임의 호출하지 않게 한다.
+
+### 3.3 persistence
+
+persisted state는 다음 metadata를 가져야 한다.
+
+```ts
+type PersistedRecord<T> = Readonly<{
+  version: number;
+  writtenAt: string;
+  value: T;
+}>;
+```
+
+- key는 typed registry가 소유한다.
+- read 시 schema parse와 migration을 거친다.
+- quota, unavailable, corrupt, version mismatch를 구분한다.
+- 민감정보와 credential을 저장하지 않는다.
+- server state persistence와 offline mutation queue는 별도 project-selected
+  adapter다.
+
+## 4. 표준 데이터 호출 경로
+
+```mermaid
+sequenceDiagram
+  actor User
+  participant Page as React page
+  participant Controller as inbound query/mutation controller
+  participant App as application input use case
+  participant Gateway as output gateway
+  participant Adapter as HTTP/generated client adapter
+  participant API as Backend/BFF
+
+  User->>Page: route or event
+  Page->>Controller: typed input
+  Controller->>App: query/command + AbortSignal
+  App->>Gateway: capability request
+  Gateway->>Adapter: DTO request
+  Adapter->>API: path/query/body/auth
+  API-->>Adapter: envelope or failure
+  Adapter-->>Gateway: parsed DTO Result
+  Gateway-->>App: mapped model Result
+  App-->>Controller: view data or AppFailure
+  Controller-->>Page: query/mutation state
+```
+
+페이지는 controller hook이 제공하는 상태만 렌더링한다. controller는 React,
+TanStack Query와 application input interface를 알 수 있지만 use case의 concrete
+구현과 outbound adapter는 모른다.
+
+### 4.1 Application API
+
+```ts
+export interface Application {
+  readonly resources: {
+    list(
+      input: ListResourcesInput,
+      context: Readonly<{ signal: AbortSignal }>,
+    ): Promise<Result<readonly ResourceSummary[], AppFailure>>;
+    create(
+      command: CreateResourceCommand,
+      context?: Readonly<{ signal?: AbortSignal }>,
+    ): Promise<Result<Resource, AppFailure>>;
+  };
+}
+```
+
+`ApplicationProvider`는 이 API를 immutable value로 제공한다. controller 외의
+presentation 코드에서 raw HTTP/storage/telemetry port를 가져오는 hook은 만들지
+않는다. theme, locale 같은 UI platform provider는 별도다.
+
+### 4.2 query adapter
+
+```ts
+export function useResourcesQuery(input: ListResourcesInput) {
+  const application = useApplication();
+
+  return useQuery({
+    queryKey: resourceKeys.list(input),
+    queryFn: async ({ signal }) =>
+      unwrapResult(await application.resources.list(input, { signal })),
+    retry: false,
+    staleTime: resourceQueryPolicy.list.staleTime,
+  });
+}
+```
+
+실제 구현 규칙:
+
+- query key는 readonly tuple factory로만 만든다.
+- key에 들어간 filter는 실제 gateway request에도 동일하게 투영한다.
+- `AbortSignal`을 application과 HTTP transport까지 전달한다.
+- HTTP 계층이 bounded retry를 소유하면 query retry는 끈다.
+- background error와 initial error의 UI를 구분한다.
+- placeholder와 cached stale data가 있을 때 전체 화면 error로 교체하지 않는다.
+- `select`는 view-only projection에 쓰고 도메인 규칙을 넣지 않는다.
+- query hook은 feature public API에서 export한다.
+
+### 4.3 mutation adapter
+
+```ts
+export function useCreateResourceMutation() {
+  const application = useApplication();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (command: CreateResourceCommand) =>
+      application.resources.create(command).then(unwrapResult),
+    onSuccess: () =>
+      queryClient.invalidateQueries({ queryKey: resourceKeys.all }),
+  });
+}
+```
+
+기본 mutation은 navigation만으로 취소됐다고 가정하지 않는다. 서버 작업의 취소가
+안전한 operation만 controller가 보관한 `AbortController`와 명시적 cancel action을
+사용한다. idempotency key는 UI 입력으로 받지 않고 application use case가
+`IdGeneratorPort`로 만들며, 같은 논리 요청의 bounded HTTP retry와 auth replay는
+동일한 key를 재사용한다.
+
+실제 구현에서는 mutation마다 다음을 명시한다.
+
+- double-submit 방지와 idempotency key 소유자
+- cancel 가능 여부
+- optimistic update 적용 여부와 rollback snapshot
+- 성공 후 invalidate/update/navigation 순서
+- 409 conflict와 422 field validation mapping
+- offline 시 queue할지 즉시 실패할지
+- analytics/telemetry event와 redaction
+
+optimistic update는 기본값이 아니다. 서버 규칙을 확실히 재현할 수 있고 rollback이
+안전한 mutation에만 사용한다.
+
+## 5. HTTP client 책임
+
+### 5.1 목표 파이프라인
+
+```text
+operation registry
+  -> path/search/body builder
+  -> credential attachment
+  -> timeout and external cancellation
+  -> bounded retry
+  -> fetch transport
+  -> status/envelope decoder
+  -> response schema decoder
+  -> feature DTO mapper
+  -> AppFailure mapper
+```
+
+각 단계의 입력과 출력은 typed result다. feature-specific model mapper를 공통 HTTP
+client 안에 넣지 않는다.
+
+### 5.2 request projection
+
+operation definition은 최소 다음 계약을 갖는다.
+
+```ts
+type OperationDefinition<
+  TPath,
+  TSearch,
+  TBody,
+  TResponse,
+> = Readonly<{
+  id: OperationId;
+  method: HttpMethod;
+  pathTemplate: string;
+  pathSchema: Schema<TPath>;
+  searchSchema: Schema<TSearch>;
+  bodySchema: Schema<TBody>;
+  responseSchema: Schema<TResponse>;
+  timeoutMs?: number;
+  retryClass: "never" | "safe" | "idempotency-keyed";
+}>;
+```
+
+규칙:
+
+- path segment는 `encodeURIComponent`에 해당하는 안전한 builder를 통과한다.
+- query의 array/null/undefined/boolean/date serialization을 한 곳에서 정의한다.
+- Zod parse 결과의 trim/default/coercion을 실제 request에 사용한다.
+- GET/HEAD에는 body를 보내지 않는다.
+- JSON content type은 body가 있을 때만 붙인다.
+- base URL과 path를 문자열 덧붙이기로 조립하지 않는다.
+- external URL은 별도 allowlist policy를 거친다.
+
+### 5.3 timeout, cancellation, retry
+
+소유권:
+
+- 사용자 navigation/unmount 취소: query/controller가 signal 생성
+- operation timeout: HTTP adapter
+- retry: HTTP adapter 또는 query adapter 중 하나
+- 인증 복구 후 단 한 번 replay: auth decorator
+- mutation idempotency: application/controller가 key 생성, operation이 허용 여부 선언
+
+retry 조건:
+
+- safe method 또는 idempotency key가 있는 허용 operation만 대상
+- timeout, network, 명시된 429/5xx만 정책 대상
+- validation, auth denial, forbidden, not found, conflict는 자동 재시도하지 않음
+- `Retry-After`와 bounded exponential backoff/jitter 지원
+- tab hidden/offline 상태를 고려
+- 최대 횟수와 전체 elapsed budget을 함께 제한
+- 각 attempt와 final failure를 redacted telemetry로 기록
+
+timer와 event listener는 성공, 실패, validation 조기 반환, external abort 모든
+경로에서 정리되어야 한다.
+
+RP-03의 현재 구현은 다음 계약을 자동 검증한다.
+
+- `request-builder.ts`가 path 값을 escape하고 search key를 정렬하며 array 순서를
+  보존한다.
+- operation의 `requestSource`가 search/body schema를 선택하고 Zod의
+  default/trim 결과만 URL 또는 JSON payload에 전달한다.
+- runtime `REQUEST_TIMEOUT_MS`와 `MAX_RETRY_ATTEMPTS`가 transport factory에
+  주입된다.
+- query adapter의 자동 retry는 끄고 HTTP만 bounded network retry를 소유한다.
+- `AsyncOverlay`는 refreshing/stale-degraded/mutation-pending/
+  mutation-conflict를 TypeScript union으로 배타화한다.
+- `useApplicationQuery`와 `useApplicationMutation`은 cancellation, stale latch,
+  duplicate submit, optimistic rollback, conflict resolution을 제공한다.
+
+## 6. 인증과 token 소유권
+
+기본 skeleton은 token manager를 제공하지 않는다.
+
+지원 profile:
+
+| profile | credential 소유자 | frontend 역할 |
+| --- | --- | --- |
+| BFF/HttpOnly cookie | browser cookie + backend | `credentials`, CSRF 정책, session probe |
+| external OIDC/Auth SDK | SDK memory/cache | attach/recover/login/logout를 auth adapter로 감쌈 |
+| SPA memory token | auth adapter memory | 프로젝트가 명시적으로 선택할 때만 |
+
+공통 `AuthSessionReader`와 HTTP 전용 `CredentialProvider`를 분리한다.
+
+```ts
+interface AuthSessionReader {
+  getSnapshot(): SessionSnapshot;
+  subscribe(listener: () => void): () => void;
+}
+
+interface CredentialProvider {
+  attach(request: RequestInit): Promise<RequestInit>;
+  recover(failure: AuthFailure): Promise<"recovered" | "not-recovered">;
+}
+```
+
+UI는 credential을 읽지 않는다. HTTP adapter는 UI session action을 호출하지
+않는다. logout/login/redirect는 application input 또는 auth UI facade를 통해
+실행한다.
+
+## 7. 오류, 검증, logging
+
+### 7.1 검증 계층
+
+| 경계 | 책임 | 예 |
+| --- | --- | --- |
+| runtime config | 앱을 안전하게 시작할 수 있는가 | URL, timeout, auth mode |
+| route codec | URL을 typed input으로 읽고 쓸 수 있는가 | page, sort, ID |
+| transport DTO | 외부 응답/요청 형식이 계약과 맞는가 | envelope, date string |
+| form | 사용자가 수정 가능한 입력 형태가 유효한가 | required, length, format |
+| application | use case precondition이 맞는가 | command 조합 |
+| domain | 항상 지켜야 할 불변식인가 | valid state transition |
+
+같은 Zod schema를 무조건 모든 계층에서 재사용하지 않는다. transport DTO, form
+value, application command, domain model이 우연히 같은 모양이어도 소유권과
+변경 이유가 다르다. 필요한 경우 mapper로 연결한다.
+
+### 7.2 사용자 오류 표면
+
+`AppFailure`를 다음 UI 상태로 매핑한다.
+
+| failure | 기본 표면 | 자동 행동 |
+| --- | --- | --- |
+| unauthenticated | auth required 또는 login transition | auth policy에 따른 1회 복구 |
+| forbidden | 권한 없음 | 없음 |
+| not-found | route/detail not-found | 없음 |
+| validation | error summary + field errors | 첫 오류 focus |
+| conflict | 현재 데이터 유지 + conflict action | 자동 overwrite 금지 |
+| rate-limited | inline retry time | 허용된 query만 지연 재시도 |
+| unavailable | cached data 또는 retry surface | policy 범위 내 retry |
+| unexpected | safe generic copy + trace ID | diagnostics emit |
+
+raw response body, stack, token, URL query, PII를 사용자 copy나 일반 log에 노출하지
+않는다.
+
+### 7.3 diagnostics와 telemetry
+
+VD-07에서 level/event 기반 `DiagnosticsPort`와 semantic
+`TelemetryPort`를 분리했다. diagnostics는 8개 event ID와 safe context
+allowlist를, telemetry는 event별 required/optional attribute와 value policy를
+사용한다.
+
+공통 요구:
+
+- log level과 event key는 닫힌 union
+- attribute allowlist와 중앙 redaction
+- 기본 adapter는 bounded memory/no-op이고 endpoint가 있을 때만 best-effort
+  HTTP queue를 사용
+- production provider SDK를 추가할 때도 port 뒤에서 감싸며 앱 코드는 SDK를
+  import하지 않음
+- 오류 객체 전체를 그대로 serialize하지 않음
+- trace ID/build ID/route ID/operation ID를 허용된 범위에서 연결
+- logging failure가 제품 flow를 실패시키지 않음
+- consent가 필요한 analytics와 essential diagnostics를 분리
+
+HTTP는 route/operation/correlation ID를 logical execution context로 생성하고
+success/recovered/failed/aborted 종료 시 diagnostics를 한 번만 기록한다.
+terminal non-abort failure만 telemetry를 한 번 발행한다. cache/storage와 boot
+producer는 raw key, value, message, stack을 버리고 error kind와 bounded
+operation만 남긴다. queue full과 sink failure는 제한된 reason bucket이며 drop
+observer가 실패해도 재귀 발행하지 않는다.
+
+### 7.4 locale, message와 표시 값
+
+RP-08부터 locale은 presentation-owned React context다. server/application
+state에 번역된 문자열을 저장하거나 query key에 locale을 넣는 것은 응답 자체가
+locale별 데이터인 경우에만 허용한다. 공통 UI copy 변경 때문에 query cache를
+복제하지 않는다.
+
+```text
+API timestamp/number/failure kind
+  -> schema + mapper (의미 값 유지)
+  -> application result
+  -> presentation controller
+  -> useLocale().date/number/message
+```
+
+- message key는 `MessageKey` union이며 interpolation은 key별 tuple type이다.
+- unknown external key는 `resolveMessage`에 전달해도 raw key가 표시되지 않는다.
+- backend `message`는 diagnostic input일 수 있지만 사용자 copy가 아니다.
+- form validation code는 `ParameterlessMessageKey` allowlist로 mapping한다.
+- date의 기본 timezone은 UTC이고 제품 timezone은 presentation 호출자가
+  명시한다.
+- pseudo/RTL locale state는 local interaction state이며 persistence와 server
+  synchronization을 기본 제공하지 않는다.
+- key rename은 typed canonical key를 먼저 이동하고 runtime alias에 migration
+  기간을 둔다.
+
+## 8. 폼 표준
+
+VD-04에 따라 현재 기본 엔진은 React native form event와 controlled value이며
+Zod를 local facade 뒤에서 사용한다. 동적 field array, 비동기 field validation,
+대규모 render isolation 요구가 실제로 생기면 public API를 유지한 채 React Hook
+Form 또는 TanStack Form adapter를 평가한다.
+
+현재 public API는 다음과 같다.
+
+- `Form`
+- `FormField`
+- `Label`
+- `Description`
+- `FieldError`
+- `ErrorSummary`
+- `useAppForm`
+- `mapValidationFailureToFields`
+- `useDirtyNavigationGuard`
+
+구현 위치:
+
+- controller와 mapping: `src/presentation/forms`
+- layout-only template: `src/presentation/templates`
+- feature form schema/command mapper:
+  `src/features/reference-feature/presentation/reference-resource-form.ts`
+- 실제 create page:
+  `src/features/reference-feature/presentation/reference-resource-form-page.tsx`
+
+`ApiFailure.validationIssues`는 HTTP 경계가 투영한 `path`와 `code`만 담는다.
+backend message와 알 수 없는 path는 field copy로 사용하지 않는다.
+
+필수 동작:
+
+1. label, description, error를 stable ID와 `aria-describedby`로 연결
+2. submit 시 error summary와 첫 오류 focus
+3. submitting 중 중복 제출 방지
+4. 422 응답의 알려진 field만 표시하고 나머지는 form-level failure로 처리
+5. 409 conflict는 validation error로 위장하지 않음
+6. 취소와 route 이탈 시 dirty policy 적용
+7. form value → application command mapper를 별도 함수로 둠
+8. browser autofill, IME composition, paste, password manager를 방해하지 않음
+9. loading skeleton으로 사용자의 입력을 덮지 않음
+10. form schema와 server contract mismatch를 integration test로 검증
+
+## 9. 새 query 추가 recipe
+
+1. feature-owned input type과 application query use case를 추가한다.
+2. 필요한 output gateway를 `ports/out`에 추가한다.
+3. transport DTO schema와 mapper를 outbound feature adapter에 추가한다.
+4. operation registry에 path/search/response/retry class를 등록한다.
+5. readonly tuple query key factory를 추가한다.
+6. inbound query controller hook을 추가한다.
+7. page template에서 loading/empty/error/refreshing/success를 렌더링한다.
+8. 다음 테스트를 추가한다.
+   - use case unit
+   - DTO mapper/schema contract
+   - path/search projection
+   - MSW success/empty/401/403/429/500/schema mismatch
+   - cancellation과 retry ownership
+   - component state
+   - route E2E
+9. registry, type, architecture, unit, integration, E2E gate를 실행한다.
+
+금지:
+
+- page에서 `fetch`
+- page에서 raw QueryClient
+- cache key와 request filter의 별도 수동 조립
+- response DTO를 domain/application model로 사용
+- initial loading과 background refreshing을 같은 full-page skeleton으로 표시
+
+## 10. 새 mutation/form 추가 recipe
+
+1. form value schema와 application command type을 분리한다.
+2. value → command mapper를 작성한다.
+3. input command use case와 output gateway method를 추가한다.
+4. operation의 idempotency/retry 정책을 선언한다.
+5. mutation controller에 invalidation/update/rollback 순서를 작성한다.
+6. `FormPageTemplate`과 공통 field primitive로 화면을 구성한다.
+7. 422, 409, unauthenticated, unavailable, abort를 각각 처리한다.
+8. dirty navigation과 double-submit을 검증한다.
+9. 다음 테스트를 추가한다.
+   - form schema와 mapper unit
+   - keyboard/label/error summary component
+   - MSW success/422/409/network-lost
+   - optimistic rollback을 쓰는 경우 cache snapshot
+   - 브라우저 navigation blocker와 성공 후 이동
+
+## 11. 완료 기준
+
+- TS/TSX가 lint, type, architecture, registry, security 검사를 우회하지 않는다.
+- source와 test가 strict typecheck된다.
+- UI는 application input API만 호출한다.
+- reference query와 mutation이 TanStack adapter를 통해 동작한다.
+- retry 책임이 단일 계층에 있고 cancellation/timeout과 충돌하지 않는다.
+- path/search/parsed body가 실제 전송값과 일치한다.
+- 상태 종류별 소유권이 테스트와 문서에서 확인된다.
+- token은 UI와 일반 storage/store에 노출되지 않는다.
+- failure와 validation의 각 계층이 typed mapper로 분리된다.
+- common UI copy, locale formatter와 direction이 typed i18n facade를 통과한다.
+- query/mutation/form recipe만으로 새 기능을 만들 수 있다.

docs/contracts/compatibility.md

@@ -0,0 +1,11 @@
+# Contract compatibility and rollback rules
+
+The blocking tuple is `(buildId, configSchemaVersion, apiContractVersion,
+assetManifestHash, releaseId)`. Versions are parsed numerically.
+
+1. additive changes preserve current required fields
+2. breaking changes require a major version bump
+3. persisted cache is discarded unless an explicit tested migration exists
+4. an incompatible config or API contract blocks product mount
+5. rollback restores HTML, assets, runtime config, API compatibility, and
+   release manifest as one coherent set

docs/operations/ci-quality-gates.md

@@ -0,0 +1,46 @@
+# CI quality-gate orchestration
+
+`config/ci/gates.json` is the executable registry for all 26 gates. The Gitea
+adapter runs each gate as an independent matrix check with full fan-out and no
+soft-fail wiring.
+
+The dependency graph is:
+
+```text
+MERGE_READY
+  -> RELEASE_READY
+    -> PROD_PROMOTION_READY
+      -> FIELD_SLO_READY
+
+DOCUMENTATION_READY (off-chain)
+```
+
+Pull requests and `develop` pushes evaluate merge readiness. Version tags
+evaluate merge then release readiness. Production and field evaluation require
+an explicit workflow dispatch. The field tier cannot pass until the 28-day
+sample threshold decision is recorded. Documentation readiness consumes the
+canonical project-note evidence in which both scoped diagrams already received
+100/100 `PASS_SCOPED`; the repo ledger preserves the evidence scope and
+canonical digests.
+
+All jobs upload the shared `artifacts/` tree even after failure. Numeric
+retention remains an organization/provider decision; the workflow intentionally
+does not invent `retention-days`. The relative minimums are recorded in the
+registry: merge evidence through the PR decision, coherent release evidence
+through the next release promotion, drill evidence through the next production
+promotion, and field evidence through aggregation.
+
+Browser-backed merge gates install and execute the pinned Chromium, Firefox,
+and WebKit engines. This makes route behavior, reflow, native dialog semantics,
+theme persistence, and automated accessibility a cross-engine contract rather
+than a Chromium-only smoke check.
+
+Repository variables required by higher tiers:
+
+- `HOSTING_BASE_URL` for live header verification
+- `FIELD_WEB_VITALS_INPUT` for the privacy-approved field sample document
+- `MIN_ELIGIBLE_SAMPLES` after the baseline decision
+
+Branch protection must mark each `FE-GATE-* / <name>` check required for its
+declared tier. This repository cannot configure server-side protection by
+committing a file.

docs/operations/performance-evidence.md

@@ -0,0 +1,22 @@
+# Performance evidence contract
+
+Performance evidence is deliberately split by measurement context:
+
+- `bundle.json` records production build output and enforces initial JavaScript
+  at 200 KiB gzip and every lazy chunk at 120 KiB gzip.
+- `lab.json` records Chromium/runner/viewport/network/CPU/cache/build context and
+  enforces LCP 2.5 s, CLS 0.10, and the named route interaction at 200 ms.
+- `field-web-vitals.json` records consent-filtered, route-ID aggregated,
+  release-specific production samples over 28 days and evaluates p75 LCP, CLS,
+  and INP against 2.5 s, 0.10, and 200 ms.
+
+The field minimum eligible-sample threshold is intentionally unresolved until
+a privacy-approved telemetry baseline exists. Therefore the field command
+fails closed with `FAIL_UNVERIFIED` when run against the example input. Provide
+`FIELD_WEB_VITALS_INPUT` and `MIN_ELIGIBLE_SAMPLES` only after that decision is
+recorded. The external input must identify a production release and an exact
+28-day export window, name the source/export, carry privacy-approval and
+threshold-decision references, and contain only non-negative route-ID samples.
+The environment threshold must be a positive integer equal to the approved
+decision embedded in the input. Invalid metadata fails as `FAIL_UNVERIFIED`;
+the example can never serve as production evidence.

docs/operations/release-cache-rollback.md

@@ -0,0 +1,32 @@
+# Release, cache, and rollback contract
+
+Each deployment is an immutable `releases/<releaseId>/` artifact set. The
+provider adapter must upload assets, release manifest, runtime config, and
+verify asset reachability before atomically switching the active HTML pointer.
+The post-switch boot, route, API, telemetry, and reload-loop smoke checks close
+the deployment.
+
+Rollback selects a prior release tuple, confirms its assets and runtime/API
+compatibility, atomically switches the complete set, performs the provider
+cache action, and repeats the smoke checks. Rebuilding an old commit, replacing
+HTML alone, or declaring recovery from cache-purge completion is prohibited.
+Recovery is established by old/new reachability probes.
+
+The provider-independent cache defaults are:
+
+- hashed assets: `public, max-age=31536000, immutable`
+- HTML: `no-cache`
+- runtime config and release manifest: `no-store`
+- public source maps: disabled
+- service worker/offline cache: disabled
+
+HTML, JSON config/manifest, and hashed JavaScript MIME types are also compared
+to the declared allowlist; a cache-correct response with a mismatched
+`Content-Type` still fails the hosting gate.
+
+`corepack pnpm verify:hosting-headers` uses a deterministic fixture locally.
+Set `HOSTING_BASE_URL` to probe deployed responses; production promotion
+requires the artifact to report `mode: "live"`. The live target must be its
+canonical, non-loopback HTTPS root URL. Each required surface must return HTTP
+200 without leaving that origin before its cache, content-type, and security
+headers can count as deployment evidence.

docs/runbooks/FE-RB-001.md

@@ -0,0 +1,9 @@
+# FE-RB-001 — Boot configuration failure
+
+Trigger on `BOOT_CONFIG_FAILURE` after the single bounded refetch fails. Stop
+product route mounting and show the safe support shell; the planned owner
+triage target is five minutes. Escalate from the environment/config owner to
+the release owner.
+
+Close only after a clean-session boot mounts the product root, config
+validation evidence passes, and repeated boot-error telemetry is absent.

docs/runbooks/FE-RB-002.md

@@ -0,0 +1,11 @@
+# FE-RB-002 — Chunk or deployment mismatch
+
+Trigger on `CHUNK_LOAD_FAILURE`, `RELEASE_MANIFEST_FAILURE`, or
+`DEPLOY_MISMATCH`. Warn when dirty state may be lost, fetch the manifest
+`no-store` once, record the release pair, and allow only one reload. The
+planned release-owner triage target is five minutes. Escalate to the hosting/CDN
+owner.
+
+Close only after entry/lazy assets are reachable, the manifest parses into a
+coherent tuple, a second automatic reload is blocked, and the critical route
+smoke passes.

docs/runbooks/FE-RB-003.md

@@ -0,0 +1,10 @@
+# FE-RB-003 — Backend API degradation
+
+Trigger when terminal network/timeout/5xx failures exceed the rolling
+five-minute threshold or on one `SCHEMA_MISMATCH`. Do not expand client retry
+caps, do not retry schema mismatches, and never retry an unkeyed mutation.
+Escalate from the API client owner to backend operations and then release
+compatibility; the planned first-classification target is ten minutes.
+
+Close only after the failure rate returns to baseline, retry amplification is
+absent, critical read/write smoke passes, and schema fixtures pass.

docs/runbooks/FE-RB-004.md

@@ -0,0 +1,9 @@
+# FE-RB-004 — Telemetry sink failure
+
+Trigger on sink network/non-2xx errors, queue overflow, or adapter
+initialization failure. Keep product flows available, bound the queue, and do
+not recursively report to the failed sink. Escalate from observability to the
+telemetry platform owner; the planned triage target is fifteen minutes.
+
+Close only after product e2e remains unaffected, delivery self-check succeeds,
+the queue drains within its bound, and the forbidden-attribute scan passes.

docs/runbooks/FE-RB-005.md

@@ -0,0 +1,13 @@
+# FE-RB-005 — Coherent release rollback
+
+Trigger on a release-blocking boot, chunk, render, API, or security defect when
+a safe forward fix is not demonstrated inside the incident window. Select a
+prior immutable release, verify its asset/config/API tuple, atomically switch
+the complete set, perform the provider cache action, and run smoke checks.
+Escalate from the release-cache owner to the release approver/hosting owner.
+The provider recovery target remains TBD until hosting is selected.
+
+Close only when compatibility and release-coherence gates pass, critical smoke
+passes, repeated `DEPLOY_MISMATCH` is absent, and the incident timeline records
+the restored release ID. Pointer-switch or cache-purge completion alone is not
+recovery evidence.

docs/security/browser-boundary.md

@@ -0,0 +1,13 @@
+# Browser security boundary
+
+The browser bundle is public. Secrets, token lifecycle, raw HTML injection,
+dynamic code execution, untrusted script URLs, and public production source
+maps are prohibited defaults.
+
+`config/hosting/security-headers.json` is the declared header set. Hosting
+verification compares that declaration with live responses. CSP deliberately
+omits `unsafe-inline` and `unsafe-eval`; production code and built assets must
+remain compatible with that baseline.
+
+Route guards are UX hints and client validation does not replace backend
+authorization or validation.

docs/security/supply-chain.md

@@ -0,0 +1,18 @@
+# Build and supply-chain gate
+
+Merge and release controls:
+
+- frozen `pnpm-lock.yaml` installation; drift is blocking
+- clean production build with hashed assets and build manifest
+- machine-readable bundle sizes and checksums
+- source plus built-asset credential-pattern scan
+- direct dependency inventory and lockfile digest
+- base/head dependency diff review record
+
+Organization-specific vulnerability severity, denied-license list, SBOM format,
+and scanner selection remain policy inputs. An approved suppression must record
+reason, owner, expiry, affected package, and compensating control. Expired
+suppressions are blocking.
+
+`artifacts/security/dependency-diff.json` is a local baseline. CI replaces it
+with the actual base/head direct and transitive lockfile diff before release.

docs/styling/design-system-platform.md

@@ -0,0 +1,884 @@
+# 디자인 시스템 플랫폼 계약
+
+이 문서는 도메인 기능을 추가하기 전에 프론트엔드 스켈레톤이 제공해야 하는
+디자인 시스템의 소유권, 계층, 기본 구성요소, 외부 라이브러리 경계, 검증 방법을
+정의한다. 목표는 특정 제품의 시각 언어를 미리 결정하는 것이 아니라, 제품 팀이
+접근성·반응형·국제화·테스트 규칙을 다시 발명하지 않고 기능 화면을 만들 수 있게
+하는 것이다.
+
+이 문서에서 `필수`는 모든 제품이 기반으로 사용할 계약을 뜻한다. `선택`은
+컴포넌트의 경계와 도입 기준은 제공하지만 실제 의존성이나 구현은 제품 요구가
+생긴 뒤 추가해도 되는 항목을 뜻한다.
+
+## 1. 현재 기준선과 확인된 공백
+
+현재 저장소에는 다음 기반이 이미 있다.
+
+- `src/presentation/styles/theme.css`
+  - 의미 기반 light/dark 색상 토큰
+  - focus indicator
+  - 반응형 앱 셸
+  - reduced-motion 처리
+- `src/presentation/providers/theme-provider.jsx`
+  - `system`, `light`, `dark` 선호도
+  - 저장소 포트를 통한 선호도 영속화
+  - 운영체제 색상 변경 구독
+- `src/presentation/components/ui/`
+  - `Button`
+  - `TextField`
+  - `Card`
+  - `Alert`
+  - `Badge`
+  - `Dialog`
+- `src/presentation/components/async-surface.jsx`
+  - 초기 로딩, 빈 화면, terminal error, background 상태
+- `src/presentation/components/state-surfaces.jsx`
+  - 인증 필요, 권한 없음, 찾을 수 없음
+- `src/presentation/forms`
+  - local form facade, field/error summary, dirty navigation dialog
+- `src/presentation/templates`
+  - Standard, Collection, Detail, Form, Status page template
+- `/examples/ui`, `/examples/states`
+  - 실행 가능한 primitive와 상태 예제
+- component/E2E/axe 테스트
+  - 필드 설명과 오류 연결
+  - native dialog 닫기와 trigger focus 복원
+  - 320px reflow
+  - Chromium, Firefox, WebKit
+  - 등록 라우트의 자동 접근성 검사
+
+RP-07 구현 이후 이 기반은 저장소 내부 디자인 시스템 플랫폼 계약을 충족한다.
+아래 목록은 구현 전 공백과 현재 해결 상태를 함께 보존한다.
+
+1. typography, elevation, motion, z-layer, control size와 breakpoint는
+   `design-system/tokens`의 3계층과 자동 gate로 닫혔다.
+2. RP-06 form/page foundation은 준비됐지만 TextArea, Select, Checkbox,
+   RadioGroup 같은 form primitive 확장은 RP-07에 남아 있다.
+3. 앱 셸, 예제와 reference feature는 public design-system barrel을 소비한다.
+4. 문자 glyph는 semantic Lucide facade로 교체됐다.
+5. token은 세 CSS 파일로 분리됐고 `theme.css`는 layout/component styling만
+   소유한다.
+6. runtime gallery는 있지만 격리된 story, interaction story, 시각 회귀 기준선이
+   없다.
+7. 사용자 문구가 한국어 literal로 고정되어 locale과 RTL 계약이 없다.
+8. page template, form과 pattern은 public barrel에서 제공된다.
+9. 모바일 navigation은 native modal Drawer로 focus 이동, 배경 비활성화,
+   Escape/link dismiss와 trigger focus restore를 제공한다.
+
+따라서 기존 구성요소는 폐기하지 않고 아래 목표 계층으로 이동·확장한다.
+
+## 2. 소유권과 의존성 원칙
+
+디자인 시스템은 `presentation` 계층이 소유한다. 색상, 아이콘, 키보드 상호작용,
+포커스, 화면 배치와 같은 문제는 도메인 규칙이 아니다.
+
+```text
+product page
+  -> template
+  -> pattern
+  -> primitive
+  -> token
+```
+
+외부 UI 라이브러리를 사용하는 경우 흐름은 다음과 같다.
+
+```text
+product page
+  -> local design-system API
+  -> local vendor facade
+  -> Lucide / React Aria / Radix
+```
+
+다음 규칙은 필수다.
+
+- 제품 페이지는 `lucide-react`, `react-aria-components`, `@radix-ui/*`를 직접
+  import하지 않는다.
+- 외부 UI 라이브러리 type을 공용 컴포넌트 API로 그대로 노출하지 않는다.
+- 도메인과 application 계층은 React component, CSS class, icon name을 알지
+  않는다.
+- primitive는 API 요청, query cache, 인증 상태와 같은 외부 상태를 직접 읽지
+  않는다.
+- pattern과 template도 application use case를 직접 선택하지 않는다. 필요한
+  상태와 command callback을 props/slot으로 받는다.
+- 제품별 색상이나 명칭을 primitive 내부에 하드코딩하지 않는다.
+- 같은 의미의 접근성·키보드 동작을 페이지마다 다시 구현하지 않는다.
+- 세 번째 사용 사례가 확인되기 전에는 제품 전용 조합을 무리하게 primitive로
+  승격하지 않는다.
+
+아이콘과 headless UI는 React inbound adapter의 vendor facade로 충분하다.
+이들을 위한 application port를 만들지 않는다. HTTP, storage, telemetry처럼
+런타임 외부 자원을 교체하는 capability와 UI 구현 라이브러리를 구분한다.
+
+## 3. 목표 디렉터리
+
+TypeScript 전환 이후의 목표 구조는 다음과 같다. 마이그레이션 중에는 기존
+경로에서 같은 소유권 규칙을 지키고, 한 번에 전체 경로를 이동하지 않아도 된다.
+
+```text
+src/adapters/inbound/react/design-system/
+  index.ts
+  tokens/
+    primitive.css
+    semantic.css
+    component.css
+    token-contract.ts
+  primitives/
+    button/
+    field/
+    checkbox/
+    dialog/
+    ...
+  patterns/
+    async-surface/
+    form/
+    data-table/
+    confirmation/
+    ...
+  templates/
+    standard-page/
+    collection-page/
+    detail-page/
+    form-page/
+    status-page/
+  icons/
+    icon.tsx
+    icon-button.tsx
+    semantic-icons.tsx
+    vendors/
+      lucide.tsx
+  vendors/
+    react-aria/
+  testing/
+    story-decorators.tsx
+    render-design-system.tsx
+```
+
+`index.ts`는 제품의 React inbound 코드가 사용할 public API다. 내부 파일 deep
+import는 디자인 시스템 자체와 테스트에만 허용한다. 이 경계는 ESLint의
+`no-restricted-imports`로 검사한다.
+
+현재 `src/presentation`은 React inbound adapter 역할을 한다. TypeScript
+마이그레이션 동안 기존 경로를 유지할 수 있지만, 최종 canonical target은 위
+경로다. 같은 컴포넌트를 `presentation`과 `adapters/inbound/react` 양쪽에
+복제하지 않고 feature 단위로 이동한다.
+
+## 4. 계층 계약
+
+### 4.1 Tokens
+
+토큰은 시각적 결정을 이름으로 표현한다. 토큰은 세 계층으로 관리한다.
+
+```text
+primitive token -> semantic token -> component token
+```
+
+예:
+
+```css
+--palette-blue-600: ...;
+--color-action: var(--palette-blue-600);
+--button-primary-background: var(--color-action);
+```
+
+#### Primitive tokens
+
+원시 palette와 scale이다. 제품 코드에서 직접 소비하지 않는다.
+
+- palette
+- spacing scale
+- font size와 line height scale
+- radius scale
+- shadow scale
+- duration과 easing scale
+- fixed size scale
+
+#### Semantic tokens
+
+제품 코드와 대부분의 primitive가 소비하는 이름이다.
+
+- `surface`, `surface-muted`, `surface-elevated`
+- `content`, `content-muted`, `content-inverse`
+- `border`, `border-strong`
+- `action`, `action-hover`, `action-pressed`
+- `danger`, `warning`, `success`, `info`
+- `focus-ring`
+- `disabled-content`, `disabled-surface`
+
+#### Component tokens
+
+특정 primitive가 여러 semantic token을 조합할 때만 사용한다.
+
+- `button-primary-background`
+- `field-border-invalid`
+- `dialog-elevation`
+- `navigation-active-background`
+
+컴포넌트 토큰은 제품별 variant를 만들기 위한 우회 경로가 아니다. 두 개 이상의
+컴포넌트가 같은 의미를 공유한다면 semantic token으로 승격한다.
+
+#### 필수 토큰 범주
+
+| 범주 | 필수 내용 |
+| --- | --- |
+| Color | surface/content/border/action/status/focus, light/dark |
+| Typography | family, size, line-height, weight, letter-spacing |
+| Spacing | inset, inline, stack, section, page spacing scale |
+| Size | control height, icon size, touch target, container width |
+| Border | width, style, semantic border |
+| Radius | control, surface, modal, full |
+| Elevation | panel, popover, dialog, sticky shell |
+| Z-layer | base, sticky, navigation, popover, modal, toast |
+| Motion | fast/normal/slow duration, standard/emphasized easing |
+| Breakpoint | compact, medium, wide와 container 계약 |
+| Opacity | disabled, scrim, skeleton |
+
+토큰의 완료 조건은 다음과 같다.
+
+- light와 dark에서 모든 semantic token이 정의된다.
+- `forced-colors`에서도 focus와 control 경계가 사라지지 않는다.
+- 상태는 색상만으로 구분하지 않는다.
+- 같은 raw value가 반복되면 named token으로 승격한다.
+- 사용자 입력으로 CSS class나 CSS variable 이름을 조립하지 않는다.
+- token contract test가 필수 token의 누락을 차단한다.
+- chart나 canvas처럼 JavaScript 값이 필요한 경우에만 typed token accessor를
+  제공한다.
+
+## 5. 기본 컴포넌트 카탈로그
+
+### 5.1 Primitives
+
+Primitive는 하나의 접근 가능한 상호작용 또는 작은 시각 단위를 제공한다.
+
+| 그룹 | 기본 제공 | 우선순위 | 핵심 계약 |
+| --- | --- | --- | --- |
+| Action | `Button` | 필수 | intent, size, disabled, pending, native semantics |
+| Action | `LinkButton` | 필수 | navigation은 anchor/router link semantics 유지 |
+| Action | `IconButton` | 필수 | accessible name 필수, 44px 권장 target |
+| Form | `Field` | 필수 | label, description, error ID 조립 |
+| Form | `TextField` | 필수 | text/email/password/search/autocomplete |
+| Form | `TextArea` | 필수 | resize와 글자 수 안내 |
+| Form | `Select` | 필수 | native 우선, 복합 선택은 headless 구현 |
+| Form | `Checkbox` | 필수 | checked/indeterminate |
+| Form | `RadioGroup` | 필수 | arrow-key와 group label |
+| Form | `Switch` | 필수 | boolean setting 전용 |
+| Form | `SearchField` | 필수 | clear action, submit semantics |
+| Feedback | `Alert` | 필수 | inline feedback와 live-region 정책 분리 |
+| Feedback | `Badge` | 필수 | color-only 금지 |
+| Feedback | `Spinner` | 필수 | accessible label 또는 decorative |
+| Feedback | `ProgressBar` | 필수 | determinate/indeterminate |
+| Feedback | `Skeleton` | 필수 | 실제 layout과 유사한 크기, reduced motion |
+| Feedback | `Toast` | 필수 | queue, 중복 방지, timeout pause |
+| Surface | `Card` | 필수 | heading level 강제 금지, label 선택 가능 |
+| Surface | `Separator` | 필수 | decorative/semantic 구분 |
+| Overlay | `Dialog` | 필수 | modal semantics, focus trap/restore, Escape |
+| Overlay | `Drawer` | 필수 | compact navigation과 side sheet |
+| Overlay | `Popover` | 필수 | anchor, dismiss, collision |
+| Overlay | `Tooltip` | 필수 | hover와 keyboard, 중요한 정보 단독 보유 금지 |
+| Overlay | `Menu` | 필수 | roving focus, typeahead, Escape |
+| Navigation | `Breadcrumbs` | 필수 | 현재 위치와 overflow |
+| Navigation | `Tabs` | 필수 | manual/automatic activation 정책 |
+| Navigation | `Pagination` | 필수 | current page, previous/next label |
+| Utility | `VisuallyHidden` | 필수 | screen-reader-only content |
+| Utility | `Portal` | 필수 | overlay root와 SSR-safe fallback |
+| Utility | `FocusRing` | 필수 | input modality 인식 |
+| Advanced | date/time picker | 선택 | locale/time zone 요구가 있을 때 |
+| Advanced | file upload/dropzone | 선택 | upload adapter 요구가 있을 때 |
+| Advanced | virtualizer/tree | 선택 | 실제 데이터 규모가 입증될 때 |
+
+Primitive API는 다음 규칙을 지킨다.
+
+- 기본 HTML semantics를 보존한다.
+- `div onClick`로 button이나 link를 흉내 내지 않는다.
+- `variant`, `size`, `tone`은 closed union과 정적 class map을 사용한다.
+- pending은 focus를 잃게 하는 무조건적인 `disabled`와 구분한다.
+- controlled와 uncontrolled 지원 여부를 문서화한다.
+- ref 전달과 focus contract를 테스트한다.
+- `className`은 escape hatch이지 public variant를 대체하지 않는다.
+- 임의의 polymorphic `as`보다 `Button`과 `LinkButton`처럼 semantics가 명확한
+  API를 우선한다.
+- visual-only prop이 도메인 의미를 표현하지 않도록 한다.
+
+### 5.2 Patterns
+
+Pattern은 여러 primitive를 조합해 반복되는 사용자 문제를 해결한다.
+
+| Pattern | 필수 내용 |
+| --- | --- |
+| `AsyncSurface` | loading, success, empty, terminal error, stale, refresh |
+| `AccessSurface` | auth required, forbidden, not found |
+| `Form` | submit, error summary, first-invalid focus, pending |
+| `ConfirmationDialog` | destructive action 설명과 명시적 확인 |
+| `ToastRegion` | queue, announcement, dismiss, focus policy |
+| `SearchFilterToolbar` | search, filter, reset, result count |
+| `DataTable` | caption, sorting, selection, responsive fallback |
+| `PaginationBar` | result range와 page navigation |
+| `NavigationDrawer` | mobile focus scope와 background inert |
+| `DisclosureGroup` | help/settings section |
+
+Pattern은 application failure object 전체를 렌더링하지 않는다. 안전한 message key,
+사용자 action, 표시 가능한 metadata만 받는다.
+
+### 5.3 Templates
+
+Template은 페이지 레이아웃과 상태 slot을 제공한다. API 호출과 도메인 use case는
+소유하지 않는다.
+
+#### `StandardPageTemplate`
+
+- breadcrumb 또는 back navigation
+- eyebrow
+- `h1`
+- description
+- status/metadata
+- primary/secondary actions
+- main content와 aside slot
+
+#### `CollectionPageTemplate`
+
+- page header
+- search/filter/sort toolbar
+- result count
+- loading/empty/error slot
+- table/list/card-grid slot
+- pagination slot
+- compact viewport에서의 대체 배치
+
+#### `DetailPageTemplate`
+
+- breadcrumb/back
+- title과 entity status
+- page actions
+- description list/section slot
+- loading/not-found/forbidden/error 상태
+
+#### `FormPageTemplate`
+
+- heading과 설명
+- error summary
+- field section
+- sticky 또는 inline action bar
+- submit/cancel
+- submitting, success, conflict
+- unsaved-change navigation blocker 연결 지점
+
+#### `StatusPageTemplate`
+
+- 401, 403, 404, 500, offline, maintenance
+- safe description
+- primary recovery action
+- optional support reference
+- raw endpoint, stack, token 노출 금지
+
+Template의 heading 순서는 slot 소비자가 임의로 깨뜨리지 못하게 예제와 테스트로
+고정한다. 다만 `Card` 같은 하위 primitive가 무조건 `h3`를 생성해서도 안 된다.
+
+## 6. Lucide 아이콘 facade
+
+[Lucide for React 공식 문서](https://lucide.dev/guide/react)는 각 아이콘을 독립
+React component로 제공하며 명시적으로 import한 아이콘만 번들에 포함될 수 있는
+tree-shaking 구조를 제공한다. 기본 아이콘 공급자로 사용하기에 적합하지만 제품
+코드가 공급자 API에 결합되면 안 된다.
+
+### 6.1 필수 규칙
+
+1. `lucide-react` import는 `icons/vendors/lucide.tsx`에서만 허용한다.
+2. 제품 코드에는 Lucide component type, icon name, stroke prop을 노출하지 않는다.
+3. 디자인 시스템이 승인한 작은 아이콘 집합만 명시적으로 import한다.
+4. 모든 아이콘을 이름으로 동적 import하는 범용 `DynamicIcon`은 기본 제공하지
+   않는다.
+5. 아이콘 색은 기본적으로 `currentColor`를 사용한다.
+6. 크기와 stroke는 `--icon-size-*`, `--icon-stroke-*` 토큰을 사용한다.
+7. 장식 아이콘은 기본적으로 `aria-hidden="true"`와 `focusable="false"`다.
+8. 정보를 단독으로 전달하는 아이콘은 local `Icon` API의 `label`을 통해
+   `role="img"`와 accessible name을 가진다.
+9. 버튼 안의 아이콘은 장식으로 처리하고 버튼 자체에 visible label 또는
+   `aria-label`을 둔다.
+10. 상태를 아이콘이나 색상 하나만으로 전달하지 않는다.
+
+### 6.2 목표 API 예시
+
+아래 예시는 방향을 설명한다. 실제 type과 경로는 TypeScript 전환 작업에서
+확정한다.
+
+```tsx
+import { MenuIcon } from "@/presentation/design-system/icons";
+import { IconButton } from "@/presentation/design-system";
+
+<IconButton accessibleName="메뉴 열기" onPress={openNavigation}>
+  <MenuIcon />
+</IconButton>
+```
+
+vendor 파일은 의미 이름과 공급자 이름을 분리한다.
+
+```tsx
+import {
+  Menu as LucideMenu,
+  X as LucideClose,
+  AlertTriangle as LucideWarning,
+} from "lucide-react";
+
+export const MenuGlyph = LucideMenu;
+export const CloseGlyph = LucideClose;
+export const WarningGlyph = LucideWarning;
+```
+
+`MenuGlyph` 같은 vendor export는 `semantic-icons.tsx` 밖으로 다시 노출하지
+않는다. 제품 코드는 `MenuIcon`, `CloseIcon`, `WarningIcon`만 사용한다.
+
+### 6.3 아이콘 추가 완료 조건
+
+- 기존 semantic icon으로 표현할 수 없는지 먼저 확인했다.
+- 서로 다른 제품 기능이 같은 의미 아이콘을 공유한다.
+- accessible name과 decorative 여부를 결정했다.
+- light/dark/high-contrast에서 보인다.
+- 200% zoom과 compact viewport에서 잘리지 않는다.
+- 신규 import 후 bundle budget을 통과한다.
+- 공급자 교체 시 제품 코드 수정이 필요하지 않다.
+
+## 7. Headless UI 선택 기준
+
+복잡한 overlay, collection, focus management를 직접 구현하기 전에 native
+platform과 검증된 headless UI를 평가한다.
+
+- [React Aria 공식 시작 문서](https://react-aria.adobe.com/getting-started)
+- [Radix Primitives 공식 소개](https://www.radix-ui.com/primitives/docs/overview/introduction)
+
+### 7.1 선택 순서
+
+1. native HTML만으로 요구 semantics와 모든 지원 브라우저 동작을 충족하는지
+   확인한다.
+2. native 구현이 불충분하면 React Aria와 Radix를 평가한다.
+3. 한 프로젝트에서 같은 문제를 해결하는 headless 공급자를 둘 이상 기본값으로
+   사용하지 않는다.
+4. 선택 결과와 버전·라이선스·bundle 영향을 ADR에 기록한다.
+5. 공급자 component를 local primitive로 감싼 뒤에만 제품 코드에 노출한다.
+
+### 7.2 평가표
+
+| 기준 | 확인 질문 |
+| --- | --- |
+| Semantics | WAI-ARIA pattern과 native semantics를 올바르게 사용하는가 |
+| Keyboard | roving focus, typeahead, Escape, arrow key가 완전한가 |
+| Focus | trap, restore, initial focus, nested overlay가 안전한가 |
+| Input modality | mouse, touch, keyboard, screen reader가 동일하게 동작하는가 |
+| i18n | RTL, locale number/date, IME를 지원하는가 |
+| Styling | semantic token과 Tailwind/CSS layer에 결합 가능한가 |
+| Bundle | component 단위 import와 tree shaking이 가능한가 |
+| React/Vite | 현재 React와 Vite 조합을 공식 지원하는가 |
+| SSR | future SSR profile에서 hydration ID가 안정적인가 |
+| Testing | 접근성·상호작용 테스트 자료와 utility가 있는가 |
+| Maintenance | release cadence, security 대응, license가 허용 가능한가 |
+
+현재 스켈레톤의 접근성·국제화 목표에는 React Aria Components가 우선 후보다.
+Radix는 overlay와 primitive composition을 중심으로 평가할 수 있다. 최종 선택은
+실제 prototype으로 `Select`, `Menu`, `Drawer` 세 가지를 구현해 다음을 비교한 뒤
+확정한다.
+
+- keyboard matrix
+- screen reader announcement
+- RTL
+- mobile touch
+- dark/high-contrast
+- gzip 증가량
+- local API로 감쌀 때 필요한 코드량
+
+공급자를 선택하더라도 `SelectProps = AriaSelectProps`처럼 vendor type alias를
+그대로 공용 API로 만들지 않는다. 제품이 실제로 지원하는 의미만 local prop으로
+닫는다.
+
+## 8. 접근성 계약
+
+목표는 WCAG 2.2 AA에 맞춘 기본 동작이다. 자동 도구 통과는 적합성 선언이 아니며,
+키보드와 보조기술 검토를 함께 수행한다.
+
+### 8.1 모든 컴포넌트의 공통 기준
+
+- 올바른 native element와 role을 사용한다.
+- visible label 또는 accessible name이 있다.
+- keyboard만으로 모든 action을 실행할 수 있다.
+- focus 순서가 DOM과 시각 순서에 맞는다.
+- focus indicator를 제거하지 않는다.
+- disabled와 readonly를 구분한다.
+- 상태는 색상만으로 전달하지 않는다.
+- 오류는 해당 control과 programmatically 연결한다.
+- 필요한 변경만 live region으로 한 번 알린다.
+- `prefers-reduced-motion`에서 불필요한 motion을 제거한다.
+- 200% text zoom과 400% page zoom에서 정보가 손실되지 않는다.
+- 320 CSS px reflow에서 양방향 scroll을 강요하지 않는다.
+- touch target은 기본 44x44 CSS px를 목표로 한다.
+- forced-colors에서 border, focus, selected state가 사라지지 않는다.
+- RTL에서 logical direction과 key behavior를 검증한다.
+- 한글·일본어·중국어 IME composition 중 입력을 조기에 검증하거나 제출하지
+  않는다.
+
+### 8.2 Overlay 기준
+
+- 열기 trigger를 기록한다.
+- 열릴 때 의미 있는 initial focus를 둔다.
+- modal일 때 focus가 내부를 벗어나지 않는다.
+- 배경 content를 `inert` 또는 동등한 방식으로 비활성화한다.
+- Escape와 명시적 닫기 action을 제공한다.
+- 닫은 뒤 trigger 또는 안전한 대체 위치로 focus를 복원한다.
+- nested overlay와 route transition 중 orphan portal을 남기지 않는다.
+
+### 8.3 Form 기준
+
+- label, description, error가 동일한 field ID 체계로 연결된다.
+- required는 시각적 기호와 programmatic 상태를 함께 가진다.
+- submit 실패 시 error summary로 focus를 이동한다.
+- error summary 항목은 해당 field로 이동한다.
+- async validation은 현재 입력보다 오래된 결과를 폐기한다.
+- pending 상태를 screen reader에 알리되 같은 문구를 반복하지 않는다.
+- 서버 오류의 raw body, stack, 내부 field path를 출력하지 않는다.
+
+## 9. 국제화 계약
+
+RP-08에서 디자인 시스템 primitive의 닫기, alert, toast, 글자 수 같은 기본
+문구는 `useLocale()` typed catalog로 이동했다. 제품 의미를 가진 label은 여전히
+명시적인 prop으로 받으며 primitive가 feature message key를 소유하지 않는다.
+
+필수 국제화 기반:
+
+- `LocaleProvider`
+- typed message key
+- fallback locale
+- `<html lang>`과 `dir` 갱신
+- `Intl.DateTimeFormat`
+- `Intl.NumberFormat`
+- `Intl.ListFormat`
+- plural/select message
+- locale별 validation message
+- pseudo-locale
+- RTL story와 E2E smoke
+
+현재 구현 위치와 실패 정책:
+
+- `presentation/i18n/catalog.ts`: 137개 canonical common key와 locale parity
+- `message-contract.ts`: key별 interpolation, fallback과 compatibility alias
+- `formatters.ts`: UTC-default date, number, relative time, list, plural/select
+- `locale-provider.tsx`: document `lang/dir`과 React consumer API
+- missing key/parameter와 formatter 예외: 빈 문자열이나 raw key 대신 안전한
+  fallback
+- `en-XA`: 긴 문자열/320px reflow, `ar-EG`: logical layout/RTL keyboard smoke
+- backend raw message와 translated HTML: 정적 negative gate에서 거절
+
+금지 패턴:
+
+- 번역 문장 중간에 JSX 문자열을 연결한다.
+- 날짜를 `substring`이나 고정 구분자로 조립한다.
+- icon direction을 locale 확인 없이 좌/우 이름으로 고정한다.
+- route title, navigation label, toast message를 JSX literal로 분산한다.
+- 번역 누락 시 빈 문자열을 렌더링한다.
+
+RP-10의 Storybook toolbar에서 최소한 다음 조합을 전환할 수 있어야 한다.
+
+- `ko-KR`, light
+- `en-US`, light
+- `en-US`, dark
+- pseudo-locale
+- 대표 RTL locale
+
+## 10. Storybook과 시각 검증
+
+현재 `/examples/ui`는 실행 중인 앱 셸과 primitive 통합을 확인하는 데 유지한다.
+그러나 runtime gallery는 isolated component workshop을 대체하지 않는다.
+
+[Storybook 공식 UI 테스트 문서](https://storybook.js.org/docs/writing-tests)는
+story를 기반으로 interaction, accessibility, visual test를 구성하는 방법을
+제공한다.
+
+### 10.1 Storybook 필수 구성
+
+- Vite 기반 Storybook
+- TypeScript CSF story
+- global theme toolbar
+- locale/RTL toolbar
+- compact/wide viewport
+- Router, Theme, Locale, Session, Query decorator
+- `@storybook/addon-a11y`
+- a11y 결과를 CI에서 error로 처리
+- interaction `play` test
+- story build gate
+
+### 10.2 각 컴포넌트의 필수 story
+
+- default
+- 모든 semantic variant
+- disabled와 readonly
+- pending/loading
+- 오류
+- 긴 문구
+- 빈 값
+- light/dark
+- compact viewport
+- keyboard interaction
+- 해당되는 경우 open/closed, controlled/uncontrolled
+
+Form과 overlay는 다음 story를 추가한다.
+
+- submit 실패와 error summary
+- async pending
+- server field error
+- Escape close
+- outside interaction
+- initial focus
+- focus restoration
+- nested content와 long content
+
+### 10.3 시각 회귀
+
+기본 시각 회귀는 Playwright `toHaveScreenshot()`을 사용해 저장소 안에서 실행할
+수 있게 한다. Chromatic 같은 외부 서비스는 선택 사항이다.
+
+필수 안정화:
+
+- 동일한 Linux image, browser version, font
+- animation과 caret 비활성화
+- 시간·랜덤·network 응답 고정
+- 동적 ID와 민감 데이터 mask
+- light/dark baseline
+- compact/wide baseline
+- 변경된 baseline은 코드 리뷰 대상
+
+failure screenshot은 시각 회귀가 아니다. 의도된 baseline과 실제 렌더링을
+비교하는 assertion이 있어야 한다.
+
+### 10.4 테스트 계층
+
+| 계층 | 검증 대상 |
+| --- | --- |
+| Type check | prop union, ref, event와 slot type |
+| Unit | token/variant map, pure formatter와 state reducer |
+| Component | native semantics, keyboard, focus, callback |
+| Story interaction | 실제 browser의 isolated behavior |
+| Story a11y | 모든 주요 state의 axe |
+| Visual | pixel/layout/theme regression |
+| E2E | 앱 셸, route, form/query integration |
+| Manual | screen reader, zoom, touch, forced-colors |
+
+DOM snapshot은 보이는 UI를 보장하지 않으므로 public markup contract가 꼭 필요한
+경우에만 사용한다.
+
+## 11. 컴포넌트 추가 Recipe
+
+새 component를 추가할 때 다음 순서를 생략하지 않는다.
+
+### Step 1. 문제와 계층을 결정한다
+
+다음 질문을 issue 또는 설계 메모에 기록한다.
+
+- 단일 control인가, 반복되는 조합인가, 페이지 구조인가?
+- primitive, pattern, template 중 어디에 속하는가?
+- 기존 component의 variant로 해결할 수 있는가?
+- 제품 전용 의미를 공통 디자인 시스템으로 잘못 올리는 것은 아닌가?
+- native HTML로 충분한가?
+
+### Step 2. 상태 행렬을 작성한다
+
+최소 상태:
+
+```text
+default
+hover
+focus-visible
+active/pressed
+disabled
+pending
+invalid
+light
+dark
+compact
+long-content
+```
+
+선택/overlay component는 open, selected, indeterminate, empty, loading도 포함한다.
+
+### Step 3. 접근성 명세를 작성한다
+
+- element/role
+- accessible name
+- keyboard table
+- focus entry/exit/restore
+- announcement
+- error association
+- reduced motion
+- touch와 screen reader
+
+명세가 불명확하면 구현보다 먼저 native, React Aria, Radix prototype으로 검증한다.
+
+### Step 4. API를 닫는다
+
+- TypeScript public props를 정의한다.
+- semantic `variant`를 사용하고 raw color prop을 노출하지 않는다.
+- callback 이름과 payload를 domain-neutral하게 정한다.
+- controlled/uncontrolled 정책을 정한다.
+- `className` escape hatch의 범위를 정한다.
+- vendor prop과 type을 public API에 노출하지 않는다.
+
+### Step 5. 필요한 토큰을 추가한다
+
+- 기존 semantic token으로 표현 가능한지 확인한다.
+- raw 값 반복을 추가하지 않는다.
+- light/dark/forced-colors 값을 함께 정의한다.
+- token contract test를 갱신한다.
+
+### Step 6. 구현한다
+
+- native semantics 우선
+- local vendor facade만 import
+- static variant map
+- ref/focus 지원
+- DOM 구조 최소화
+- render 중 전역 상태 변경 금지
+- 제품 API나 application service import 금지
+
+### Step 7. Story를 작성한다
+
+- 상태 행렬을 모두 story로 표현한다.
+- interaction test를 작성한다.
+- dark, compact, long-content를 포함한다.
+- a11y test를 error mode로 실행한다.
+
+### Step 8. 자동 테스트를 작성한다
+
+- role/name 중심 query
+- keyboard와 focus
+- disabled/pending
+- callback
+- controlled state
+- 오류와 live region
+- 필요한 visual baseline
+
+구현 class나 내부 DOM 순서만 확인하는 brittle test는 피한다.
+
+### Step 9. 통합 예제를 추가한다
+
+- `/examples/ui`에는 primitive를 추가한다.
+- `/examples/states`에는 새로운 공통 상태를 추가한다.
+- pattern/template은 domain-neutral fixture로 실제 조합을 보여 준다.
+- production profile에서 예제 route를 제외할 수 있는 계약을 유지한다.
+
+### Step 10. 문서와 public export를 갱신한다
+
+- 사용 목적
+- 사용하지 말아야 할 경우
+- props와 variant
+- keyboard
+- 접근성 책임
+- i18n
+- 예제
+- public `index.ts` export
+- 변경 로그
+
+### Step 11. 게이트를 실행한다
+
+최소 실행 범위:
+
+```bash
+corepack pnpm check:types
+corepack pnpm lint
+corepack pnpm check:architecture
+corepack pnpm test:component
+corepack pnpm test:e2e
+corepack pnpm test:a11y
+corepack pnpm build
+corepack pnpm check:bundle
+```
+
+Storybook과 visual gate가 도입된 뒤에는 story build, interaction, story a11y,
+visual comparison도 필수로 추가한다.
+
+## 12. Definition of Done
+
+컴포넌트는 아래 항목 중 자신의 state/capability matrix에 해당하는 항목을
+충족해야 `완료`다. 적용되지 않는 항목은 체크를 생략하지 말고 `N/A`와 이유를
+component contract에 기록한다. 예를 들어 `Separator`에는 pending/error/IME가,
+읽기 전용 `Card`에는 controlled state와 field error가 적용되지 않는다.
+
+### API와 아키텍처
+
+- [ ] primitive/pattern/template 소유권이 명확하다.
+- [ ] public TypeScript API가 closed union으로 정의되었다.
+- [ ] 제품 코드가 vendor package를 직접 import하지 않는다.
+- [ ] domain/application dependency가 없다.
+- [ ] public barrel을 통해 소비할 수 있다.
+- [ ] 상태를 소유하는 경우 controlled/uncontrolled 계약이 문서화되었고, focus
+      target이 있는 경우 ref 계약이 문서화되었다.
+
+### Styling
+
+- [ ] raw 색상과 반복되는 임의 값이 없다.
+- [ ] semantic token을 사용한다.
+- [ ] light/dark가 완성되었다.
+- [ ] compact/wide reflow가 된다.
+- [ ] long text와 번역 확장을 견딘다.
+- [ ] forced-colors에서도 의미가 유지된다.
+- [ ] bundle budget을 통과한다.
+
+### 접근성
+
+- [ ] native semantics와 accessible name이 있다.
+- [ ] keyboard 동작이 명세와 일치한다.
+- [ ] focus indicator, 이동, 복원이 올바르다.
+- [ ] 상태가 색상에만 의존하지 않는다.
+- [ ] 오류나 설명을 제공하는 component는 이들을 programmatically 연결한다.
+- [ ] reduced-motion을 존중한다.
+- [ ] 200%/400% zoom과 320px reflow를 확인했다.
+- [ ] screen reader 수동 검토 항목이 정의되었다.
+
+### 국제화
+
+- [ ] 사용자 문구를 소유하는 component는 이를 내부 literal로 고정하지 않는다.
+- [ ] 날짜·숫자·목록을 표시하는 component는 locale formatter를 사용한다.
+- [ ] pseudo-locale에서 잘리지 않는다.
+- [ ] RTL에서 배치와 키보드가 올바르다.
+- [ ] 문자 입력을 받는 component는 IME 입력을 깨뜨리지 않는다.
+
+### 테스트와 문서
+
+- [ ] component behavior test가 있다.
+- [ ] 모든 주요 상태 story가 있다.
+- [ ] story interaction test가 있다.
+- [ ] automated a11y가 통과한다.
+- [ ] 필요한 visual baseline이 있다.
+- [ ] runtime gallery 또는 pattern fixture가 있다.
+- [ ] 사용법, 금지 사례, 접근성 책임이 문서화되었다.
+- [ ] 전체 품질·아키텍처·bundle gate가 통과한다.
+
+## 13. 금지 패턴
+
+- 제품 페이지에서 `lucide-react` 직접 import
+- 제품 페이지에서 React Aria/Radix 직접 import
+- `div`와 keyboard handler로 native button을 재구현
+- icon-only button에 accessible name 누락
+- 문자열 icon name으로 전체 icon package를 동적 로딩
+- 사용자 값으로 Tailwind/CSS class 조립
+- raw hex/OKLCH 값을 JSX나 component CSS에 반복
+- `as="div"`처럼 semantics를 무제한 변경하는 public API
+- primitive에서 API/query/auth/storage를 직접 호출
+- 모든 상태를 하나의 전역 store에 저장
+- 오류 raw body, URL, header, token, stack 표시
+- locale 문장을 문자열 덧셈으로 구성
+- axe 통과만으로 접근성 완료 선언
+- failure screenshot만으로 시각 회귀 완료 선언
+- Storybook story 없이 runtime gallery 하나로 모든 variant를 대표
+
+## 14. 단계별 도입 순서
+
+1. TypeScript public API와 디자인 시스템 public barrel을 만든다.
+2. token을 primitive/semantic/component 계층으로 분리한다.
+3. 기존 Button, TextField, Card, Alert, Badge, Dialog를 새 계약으로 이동한다.
+4. Lucide local facade와 `IconButton`을 추가하고 문자 glyph를 제거한다.
+5. Field foundation과 필수 form primitives를 추가한다.
+6. React Aria와 Radix prototype을 비교하고 headless ADR을 확정한다.
+7. Drawer, Select, Menu, Popover, Tooltip을 local facade로 구현한다.
+8. pattern과 page template을 추가한다.
+9. locale provider, pseudo-locale, RTL 검증을 추가한다.
+10. Storybook, story a11y, interaction test를 추가한다.
+11. pinned browser 환경의 visual regression gate를 추가한다.
+12. `/examples/ui`와 `/examples/states`를 통합 smoke gallery로 유지한다.
+
+이 순서는 라이브러리 수를 늘리는 것이 목표가 아니다. 각 단계가 제품 개발자가
+중복 구현할 문제를 하나씩 제거하고, 외부 공급자를 교체할 수 있는 로컬 계약과
+검증 증거를 남기는 것이 목표다.

docs/styling/design-tokens.md

@@ -0,0 +1,49 @@
+# Design-token styling contract
+
+`src/presentation/styles/theme.css` is the styling SSOT. Components consume
+semantic color, spacing, typography, status, and radius tokens through static
+classes. `/examples/ui` is the executable token and primitive gallery.
+
+## Theme contract
+
+The supported public preference is the closed set `system`, `light`, and
+`dark`. `ThemeProvider` reads and writes `COLOR_SCHEME` through the application
+storage port; it does not access a raw storage key. `system` subscribes to
+`prefers-color-scheme` changes. Bootstrap applies the persisted preference
+before React paints.
+
+Components use semantic tokens such as `--color-panel`, `--color-content`,
+`--color-border`, `--color-action`, and status surface/content/border triples.
+They must not hard-code a light-only panel or text color. Both light and dark
+surfaces are included in automated axe checks.
+
+## Included primitives
+
+- `Button`: primary, secondary, danger, and ghost intent
+- `TextField`: label, help text, required state, and associated validation error
+- `Card`: labelled surface with optional footer
+- `Alert` and `Badge`: non-color-only status feedback
+- `Dialog`: native modal semantics, Escape/backdrop close, and trigger focus
+  restoration
+- async and access state surfaces: loading, refresh, empty, terminal error,
+  auth required, forbidden, and not found
+
+Arbitrary-value policy:
+
+- prefer a named semantic token
+- bracket values are allowed only for one-off platform constraints that cannot
+  be expressed by the current scale
+- a repeated bracket value must be promoted into `@theme`
+- user-controlled or runtime-composed class strings are forbidden
+- class variants must be selected from a closed static map
+
+The removable reference feature may demonstrate tokens, but generic production
+starter modules do not import its domain, application, adapter, or presentation
+implementation.
+
+This file documents the currently implemented token and primitive baseline.
+The [design-system platform contract](./design-system-platform.md) defines the
+target token layers, component catalog, local Lucide/headless-library
+facades, page patterns, accessibility and internationalization rules, isolated
+workshop, and component-authoring recipe. Items in that target document are not
+treated as implemented until their acceptance tests pass.

docs/testing/taxonomy.md

@@ -12,6 +12,13 @@ Each gate is blocking in its declared scope. Failures are not downgraded with
 | end-to-end | `pnpm test:e2e` | `artifacts/tests/e2e/` |
 | accessibility | `pnpm test:a11y` | `artifacts/tests/a11y.json` |
 
+End-to-end and automated accessibility scenarios run on the pinned Chromium,
+Firefox, and WebKit engines. The responsive contract explicitly exercises
+320px reflow, a mobile navigation drawer, and a wide two-column gallery.
+Theme scenarios verify persistence, operating-system changes, and dark-surface
+axe results. Native modal focus and validation association are exercised in
+both component and browser tests.
+
 A control is verified only when a positive fixture passes and its deliberately
 failing negative fixture is rejected. Generated evidence is retained by CI;
 the repository tracks only the evidence directory structure.
@@ -22,3 +29,10 @@ Promotion is an AND graph:
 2. merge gates plus release gates
 3. release gates plus rollback/runbook drills
 4. production promotion plus eligible field Web Vitals evidence
+
+This file describes the currently registered taxonomy. The
+[frontend platform testing strategy](./frontend-platform-testing-strategy.md)
+documents the target additions: test TypeScript projects, real bootstrap
+composition tests, shared MSW scenarios, query/mutation/form/router coverage,
+Storybook interaction and accessibility checks, visual regression, and a
+built-output Playwright profile.

eslint.config.js

@@ -1,6 +1,10 @@
+import babelParser from "@babel/eslint-parser";
 import eslint from "@eslint/js";
+import reactHooks from "eslint-plugin-react-hooks";
 import globals from "globals";
 
+const sourceExtensions = "{js,jsx,mjs,ts,tsx,mts}";
+
 const layerPatterns = {
   domain: [
     "**/application/**",
@@ -19,7 +23,12 @@ const layerPatterns = {
     "react-dom",
     "@tanstack/**",
   ],
-  presentation: ["**/adapters/**", "**/bootstrap/**", "@tanstack/**"],
+  presentation: [
+    "**/adapters/**",
+    "**/bootstrap/**",
+    "**/application/ports/out/**",
+    "@tanstack/**",
+  ],
   adapters: ["**/presentation/**", "**/bootstrap/**"],
 };
 
@@ -27,6 +36,38 @@ function restrictedImports(patterns) {
   return ["error", { patterns }];
 }
 
+const commonLanguageOptions = {
+  ecmaVersion: "latest",
+  sourceType: "module",
+  globals: {
+    ...globals.browser,
+    ...globals.node,
+  },
+};
+
+const commonSecurityRules = {
+  "no-eval": "error",
+  "no-new-func": "error",
+  "no-script-url": "error",
+  "no-restricted-syntax": [
+    "error",
+    {
+      selector: "JSXAttribute[name.name='dangerouslySetInnerHTML']",
+      message: "Raw HTML injection is prohibited by FE-OC-019.",
+    },
+    {
+      selector:
+        "CallExpression[callee.object.name='document'][callee.property.name='createElement'][arguments.0.value='script']",
+      message: "Runtime script construction is prohibited by FE-OC-019.",
+    },
+  ],
+};
+
+const hookRules = {
+  "react-hooks/rules-of-hooks": "error",
+  "react-hooks/exhaustive-deps": "error",
+};
+
 export default [
   {
     ignores: [
@@ -35,51 +76,216 @@ export default [
       "artifacts/**",
       "tests/fixtures/typecheck/**",
       "tests/fixtures/architecture/forbidden/**",
+      "tests/fixtures/diagnostics/forbidden/**",
+      "tests/fixtures/i18n/forbidden/**",
+      "tests/fixtures/security/forbidden/**",
     ],
   },
   eslint.configs.recommended,
   {
-    files: ["**/*.{js,jsx,mjs}"],
+    files: [`**/*.${sourceExtensions}`],
     languageOptions: {
-      ecmaVersion: "latest",
+      ...commonLanguageOptions,
-      sourceType: "module",
-      globals: {
-        ...globals.browser,
-        ...globals.node,
-      },
       parserOptions: {
         ecmaFeatures: { jsx: true },
       },
     },
+    plugins: {
+      "react-hooks": reactHooks,
+    },
+    rules: {
+      ...commonSecurityRules,
+      ...hookRules,
+    },
   },
   {
-    files: ["src/domain/**/*.{js,jsx}"],
+    files: ["**/*.{ts,mts}"],
+    languageOptions: {
+      ...commonLanguageOptions,
+      parser: babelParser,
+      parserOptions: {
+        requireConfigFile: false,
+        babelOptions: {
+          plugins: [
+            ["@babel/plugin-syntax-typescript", { isTSX: false }],
+          ],
+        },
+      },
+    },
+    rules: {
+      "no-undef": "off",
+      "no-unused-vars": "off",
+    },
+  },
+  {
+    files: ["**/*.d.ts"],
+    languageOptions: {
+      ...commonLanguageOptions,
+      parser: babelParser,
+      parserOptions: {
+        requireConfigFile: false,
+        babelOptions: {
+          plugins: [
+            ["@babel/plugin-syntax-typescript", { dts: true }],
+          ],
+        },
+      },
+    },
+    rules: {
+      "no-undef": "off",
+      "no-unused-vars": "off",
+    },
+  },
+  {
+    files: ["**/*.tsx"],
+    languageOptions: {
+      ...commonLanguageOptions,
+      parser: babelParser,
+      parserOptions: {
+        requireConfigFile: false,
+        babelOptions: {
+          plugins: [
+            [
+              "@babel/plugin-syntax-typescript",
+              { allExtensions: true, isTSX: true },
+            ],
+            "@babel/plugin-syntax-jsx",
+          ],
+        },
+      },
+    },
+    rules: {
+      "no-undef": "off",
+      "no-unused-vars": "off",
+    },
+  },
+  {
+    files: [`src/domain/**/*.${sourceExtensions}`],
     rules: {
       "no-restricted-imports": restrictedImports(layerPatterns.domain),
-      "no-restricted-globals": ["error", "window", "document", "localStorage", "fetch"],
+      "no-restricted-globals": [
+        "error",
+        "window",
+        "document",
+        "localStorage",
+        "fetch",
+      ],
     },
   },
   {
-    files: ["src/application/**/*.{js,jsx}"],
+    files: [`src/application/**/*.${sourceExtensions}`],
     rules: {
       "no-restricted-imports": restrictedImports(layerPatterns.application),
-      "no-restricted-globals": ["error", "window", "document", "localStorage", "fetch"],
+      "no-restricted-globals": [
+        "error",
+        "window",
+        "document",
+        "localStorage",
+        "fetch",
+      ],
     },
   },
   {
-    files: ["src/presentation/**/*.{js,jsx}"],
+    files: [`src/presentation/**/*.${sourceExtensions}`],
     rules: {
       "no-restricted-imports": restrictedImports(layerPatterns.presentation),
+      "no-restricted-globals": [
+        "error",
+        "fetch",
+        "localStorage",
+        "sessionStorage",
+      ],
     },
   },
   {
-    files: ["src/adapters/**/*.{js,jsx}"],
+    files: [
+      `src/presentation/adapters/query/**/*.${sourceExtensions}`,
+    ],
+    rules: {
+      "no-restricted-imports": restrictedImports([
+        "**/adapters/http/**",
+        "**/adapters/storage/**",
+        "**/adapters/auth/**",
+        "**/bootstrap/**",
+        "**/application/ports/out/**",
+      ]),
+    },
+  },
+  {
+    files: [`src/presentation/templates/**/*.${sourceExtensions}`],
+    rules: {
+      "no-restricted-imports": restrictedImports([
+        "**/application/**",
+        "**/adapters/**",
+        "**/bootstrap/**",
+        "@tanstack/**",
+      ]),
+    },
+  },
+  {
+    files: [`src/adapters/**/*.${sourceExtensions}`],
     rules: {
       "no-restricted-imports": restrictedImports(layerPatterns.adapters),
     },
   },
   {
-    files: ["tests/**/*.{js,jsx}"],
+    files: [`src/features/*/domain/**/*.${sourceExtensions}`],
+    rules: {
+      "no-restricted-imports": restrictedImports(layerPatterns.domain),
+      "no-restricted-globals": [
+        "error",
+        "window",
+        "document",
+        "localStorage",
+        "fetch",
+      ],
+    },
+  },
+  {
+    files: [`src/features/*/application/**/*.${sourceExtensions}`],
+    rules: {
+      "no-restricted-imports": restrictedImports(layerPatterns.application),
+      "no-restricted-globals": [
+        "error",
+        "window",
+        "document",
+        "localStorage",
+        "fetch",
+      ],
+    },
+  },
+  {
+    files: [`src/features/*/presentation/**/*.${sourceExtensions}`],
+    rules: {
+      "no-restricted-imports": restrictedImports([
+        "**/features/*/adapters/**",
+        "**/adapters/http/**",
+        "**/adapters/storage/**",
+        "**/adapters/auth/**",
+        "**/bootstrap/**",
+        "**/application/ports/out/**",
+        "@tanstack/**",
+      ]),
+      "no-restricted-globals": [
+        "error",
+        "fetch",
+        "localStorage",
+        "sessionStorage",
+      ],
+    },
+  },
+  {
+    files: [`src/features/*/adapters/**/*.${sourceExtensions}`],
+    rules: {
+      "no-restricted-imports": restrictedImports([
+        "**/presentation/**",
+        "**/bootstrap/**",
+        "@tanstack/**",
+      ]),
+    },
+  },
+  {
+    files: [`tests/**/*.${sourceExtensions}`],
     languageOptions: {
       globals: {
         ...globals.browser,
@@ -88,14 +294,24 @@ export default [
     },
   },
   {
-    files: ["tests/fixtures/architecture/forbidden/**/*.{js,jsx}"],
+    files: [
+      `tests/fixtures/architecture/forbidden/**/*.${sourceExtensions}`,
+    ],
     rules: {
       "no-restricted-imports": restrictedImports([
         "**/adapters/**",
+        "**/application/ports/out/**",
         "@tanstack/**",
         "react",
         "react-dom",
+        "**/application/**",
       ]),
+      "no-restricted-globals": [
+        "error",
+        "fetch",
+        "localStorage",
+        "sessionStorage",
+      ],
     },
   },
 ];

package.json

@@ -5,27 +5,70 @@
   "type": "module",
   "packageManager": "pnpm@11.17.0",
   "engines": {
-    "node": ">=24.0.0 <25.0.0",
+    "node": ">=24.11.0 <25.0.0",
     "pnpm": ">=11.0.0 <12.0.0"
   },
   "scripts": {
     "dev": "vite",
     "build": "vite build && node scripts/generate-build-manifest.mjs",
+    "build:release": "corepack pnpm build && corepack pnpm generate:supply-chain && corepack pnpm scan:security",
     "preview": "vite preview",
     "lint": "eslint src scripts tests vite.config.js vitest.config.js playwright.config.js --max-warnings=0",
     "check:architecture": "node scripts/check-architecture.mjs",
-    "check:types": "tsc --allowJs --checkJs --noEmit",
+    "check:design-system": "node scripts/check-design-system.mjs",
-    "check:types:fixture": "tsc --allowJs --checkJs --noEmit --target ES2022 --module NodeNext --moduleResolution NodeNext tests/fixtures/typecheck/invalid-port-call.js",
+    "check:design-system:fixture": "node scripts/check-design-system.mjs --fixture",
+    "check:i18n": "node scripts/check-i18n.mjs",
+    "check:i18n:fixture": "node scripts/check-i18n.mjs --fixture",
+    "check:diagnostics": "node scripts/check-diagnostics.mjs",
+    "check:diagnostics:fixture": "node scripts/check-diagnostics.mjs --fixture",
+    "check:types": "corepack pnpm check:types:app && corepack pnpm check:types:node && corepack pnpm check:types:test",
+    "check:types:app": "tsc --project tsconfig.app.json",
+    "check:types:node": "tsc --project tsconfig.node.json",
+    "check:types:test": "tsc --project tsconfig.test.json",
+    "check:types:fixture": "tsc --ignoreConfig --allowJs --checkJs --noEmit --target ES2022 --module NodeNext --moduleResolution NodeNext tests/fixtures/typecheck/invalid-port-call.js",
+    "check:types:fixture:ts-port": "tsc --ignoreConfig --strict --noEmit --target ES2022 --module ESNext --moduleResolution Bundler tests/fixtures/typecheck/invalid-port-implementation.ts",
+    "check:types:fixture:ts-result": "tsc --ignoreConfig --strict --noEmit --target ES2022 --module ESNext --moduleResolution Bundler tests/fixtures/typecheck/invalid-result-narrowing.ts",
+    "check:types:fixture:application-output": "tsc --ignoreConfig --allowJs --checkJs --strict --noEmit --skipLibCheck --target ES2022 --module ESNext --moduleResolution Bundler tests/fixtures/typecheck/invalid-application-output.ts",
+    "check:types:fixture:application-input": "tsc --ignoreConfig --allowJs --checkJs --strict --noEmit --skipLibCheck --target ES2022 --module ESNext --moduleResolution Bundler tests/fixtures/typecheck/invalid-application-input.ts",
+    "check:types:fixture:async-overlay": "tsc --ignoreConfig --allowJs --checkJs --strict --noEmit --skipLibCheck --target ES2022 --module ESNext --moduleResolution Bundler tests/fixtures/typecheck/invalid-async-overlay.ts",
+    "check:types:fixture:route-runtime": "tsc --ignoreConfig --allowJs --checkJs --strict --noEmit --skipLibCheck --target ES2022 --module ESNext --moduleResolution Bundler tests/fixtures/typecheck/invalid-route-runtime.ts",
+    "check:types:fixture:page-action": "tsc --ignoreConfig --allowJs --checkJs --strict --noEmit --skipLibCheck --target ES2022 --module ESNext --moduleResolution Bundler --jsx react-jsx tests/fixtures/typecheck/invalid-page-action.tsx",
+    "check:types:fixture:icon-button": "tsc --ignoreConfig --allowJs --checkJs --strict --noEmit --skipLibCheck --target ES2022 --module ESNext --moduleResolution Bundler --jsx react-jsx tests/fixtures/typecheck/invalid-icon-button.tsx",
+    "check:types:fixture:i18n-key": "tsc --ignoreConfig --strict --noEmit --skipLibCheck --target ES2022 --module ESNext --moduleResolution Bundler tests/fixtures/typecheck/invalid-message-key.ts",
+    "check:types:fixture:i18n-params": "tsc --ignoreConfig --strict --noEmit --skipLibCheck --target ES2022 --module ESNext --moduleResolution Bundler tests/fixtures/typecheck/invalid-message-params.ts",
+    "check:types:fixture:diagnostics": "tsc --ignoreConfig --strict --noEmit --skipLibCheck --target ES2022 --module ESNext --moduleResolution Bundler tests/fixtures/typecheck/invalid-diagnostics-port.ts",
     "test:runtime-schema": "vitest run tests/runtime-schema --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/runtime-schema.xml --passWithNoTests",
     "test:unit": "vitest run tests/unit --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/unit.xml",
     "test:component": "vitest run tests/component --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/component.xml",
     "test:integration": "vitest run tests/integration --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/integration.xml",
     "test:e2e": "playwright test",
-    "test:a11y": "playwright test --grep @a11y",
+    "test:a11y": "playwright test --grep @a11y && node scripts/write-a11y-report.mjs",
-    "test:all": "pnpm test:runtime-schema && pnpm test:unit && pnpm test:component && pnpm test:integration"
+    "review:a11y-manual": "node scripts/verify-a11y-manual.mjs",
+    "test:sample-removal": "node scripts/test-sample-removal.mjs",
+    "test:reference-feature": "vitest run tests/features/reference-feature --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/reference-feature.xml --passWithNoTests",
+    "test:all": "corepack pnpm test:runtime-schema && corepack pnpm test:unit && corepack pnpm test:component && corepack pnpm test:integration && corepack pnpm test:reference-feature",
+    "verify:lockfile": "corepack pnpm install --frozen-lockfile",
+    "generate:supply-chain": "node scripts/generate-supply-chain.mjs",
+    "scan:security": "node scripts/security-scan.mjs",
+    "check:browser-security": "node scripts/check-browser-security.mjs",
+    "check:registries": "node scripts/check-registries.mjs",
+    "check:registries:fixture": "node scripts/check-registries.mjs --governance tests/fixtures/registry/forbidden/governance.json --artifact artifacts/quality/registry-fixture.json",
+    "check:routes:fixture": "node scripts/check-registries.mjs --governance tests/fixtures/registry/routes/governance.json --artifact artifacts/quality/route-registry-fixture.json",
+    "verify:compatibility": "node scripts/check-compatibility.mjs",
+    "verify:release": "node scripts/verify-release.mjs",
+    "verify:hosting-headers": "node scripts/verify-hosting-headers.mjs",
+    "check:bundle": "node scripts/generate-supply-chain.mjs && node scripts/check-bundle.mjs",
+    "test:performance": "node scripts/test-performance.mjs",
+    "collect:web-vitals-evidence": "node scripts/collect-web-vitals-evidence.mjs",
+    "drill:runbook": "node scripts/drill-runbook.mjs",
+    "drill:runbooks": "corepack pnpm drill:runbook -- FE-RB-001 && corepack pnpm drill:runbook -- FE-RB-002 && corepack pnpm drill:runbook -- FE-RB-003 && corepack pnpm drill:runbook -- FE-RB-004 && corepack pnpm drill:runbook -- FE-RB-005",
+    "ci:gate": "node scripts/run-ci-gate.mjs",
+    "check:ci": "node scripts/check-ci-contract.mjs",
+    "verify:documentation": "node scripts/verify-documentation-readiness.mjs"
   },
   "dependencies": {
     "@tanstack/react-query": "5.101.4",
+    "lucide-react": "1.25.0",
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "react-router-dom": "7.18.1",
@@ -33,8 +76,13 @@
   },
   "devDependencies": {
     "@axe-core/playwright": "4.12.1",
+    "@babel/core": "8.0.1",
+    "@babel/eslint-parser": "8.0.1",
+    "@babel/plugin-syntax-jsx": "8.0.1",
+    "@babel/plugin-syntax-typescript": "8.0.3",
     "@eslint/js": "10.0.1",
     "@playwright/test": "1.62.0",
+    "@tailwindcss/vite": "4.3.3",
     "@testing-library/jest-dom": "7.0.0",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.6.1",
@@ -44,9 +92,11 @@
     "@vitejs/plugin-react": "6.0.4",
     "dependency-cruiser": "18.1.0",
     "eslint": "10.8.0",
+    "eslint-plugin-react-hooks": "7.1.1",
     "globals": "17.7.0",
     "jsdom": "29.1.1",
     "msw": "2.15.0",
+    "tailwindcss": "4.3.3",
     "typescript": "7.0.2",
     "vite": "8.1.5",
     "vitest": "4.1.10"

playwright.config.js

@@ -13,11 +13,13 @@ export default defineConfig({
     screenshot: "only-on-failure",
   },
   webServer: {
-    command: "pnpm dev --host 127.0.0.1",
+    command: "corepack pnpm dev --host 127.0.0.1",
     url: "http://127.0.0.1:5173",
     reuseExistingServer: !process.env.CI,
   },
   projects: [
     { name: "chromium", use: { ...devices["Desktop Chrome"] } },
+    { name: "firefox", use: { ...devices["Desktop Firefox"] } },
+    { name: "webkit", use: { ...devices["Desktop Safari"] } },
   ],
 });

public/config.json

@@ -4,7 +4,7 @@
   "REQUEST_TIMEOUT_MS": 10000,
   "MAX_RETRY_ATTEMPTS": 2,
   "TELEMETRY_ENABLED": false,
-  "AUTH_MODE": "external",
+  "AUTH_MODE": "demo",
   "CONFIG_SCHEMA_VERSION": "1",
   "API_CONTRACT_VERSION": "1",
   "RELEASE_MANIFEST_URL": "/release-manifest.json",

public/release-manifest.json

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": 1,
+  "appVersion": "0.1.0",
+  "buildId": "local-build",
+  "commitSha": "local",
+  "configSchemaVersion": "1",
+  "apiContractVersion": "1",
+  "assetManifestHash": "generated-during-build",
+  "releaseId": "local-release",
+  "builtAt": "1970-01-01T00:00:00.000Z",
+  "routeChunks": {
+    "route-home": "src/presentation/pages/home-page.jsx",
+    "route-examples-ui": "src/presentation/examples/ui-gallery-page.jsx",
+    "route-examples-states": "src/presentation/examples/state-gallery-page.jsx",
+    "route-examples-auth": "src/presentation/examples/auth-example-page.jsx",
+    "route-reference-resources": "src/features/reference-feature/presentation/reference-resource-page.tsx",
+    "route-reference-resource-detail": "src/features/reference-feature/presentation/reference-resource-detail-page.tsx",
+    "route-reference-resource-form": "src/features/reference-feature/presentation/reference-resource-form-page.tsx",
+    "route-reference-resource-status": "src/features/reference-feature/presentation/reference-resource-status-page.tsx",
+    "route-not-found": "src/presentation/pages/not-found-page.jsx"
+  }
+}

schemas/artifacts/build-manifest.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "build-manifest.schema.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "buildId",
+    "commitSha",
+    "generatedAt",
+    "buildContext",
+    "outputs"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "buildId": { "type": "string", "minLength": 1 },
+    "commitSha": { "type": "string", "minLength": 1 },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "buildContext": {
+      "type": "object",
+      "required": ["nodeVersion", "packageManagerVersion", "runnerImage"],
+      "properties": {
+        "nodeVersion": { "type": "string" },
+        "packageManagerVersion": { "type": "string" },
+        "runnerImage": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "outputs": {
+      "type": "object",
+      "required": ["directory", "viteManifest"],
+      "properties": {
+        "directory": { "type": "string" },
+        "viteManifest": { "type": "string" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

schemas/artifacts/registry-snapshot.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "generatedAt",
+    "compatibilityImpact",
+    "failures",
+    "registries"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "compatibilityImpact": {
+      "enum": ["none", "additive", "behavior-change", "breaking"]
+    },
+    "failures": { "type": "array", "maxItems": 0 },
+    "registries": {
+      "type": "array",
+      "minItems": 8,
+      "maxItems": 8,
+      "items": {
+        "type": "object",
+        "required": ["registryId", "owner", "source", "rowCount", "rows"]
+      }
+    }
+  },
+  "additionalProperties": false
+}

scripts/check-architecture.mjs

@@ -1,4 +1,4 @@
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, readdir, writeFile } from "node:fs/promises";
 import { spawnSync } from "node:child_process";
 
 await mkdir("artifacts/quality", { recursive: true });
@@ -60,10 +60,51 @@ const forbidden = runPnpm(
   ],
 );
 
-if (allowed.status !== 0 || forbidden.status === 0) {
+/** @param {string} directory @returns {Promise<string[]>} */
+async function fixtureFiles(directory) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const files = await Promise.all(
+    entries.map((entry) => {
+      const target = `${directory}/${entry.name}`;
+      return entry.isDirectory()
+        ? fixtureFiles(target)
+        : /\.(?:js|jsx|mjs|ts|tsx|mts)$/.test(entry.name)
+          ? [target]
+          : [];
+    }),
+  );
+  return files.flat();
+}
+
+const forbiddenResults = await Promise.all(
+  (await fixtureFiles("tests/fixtures/architecture/forbidden")).map((file) => ({
+    file,
+    result: runPnpm([
+      "exec",
+      "eslint",
+      file,
+      "--no-ignore",
+      "--max-warnings=0",
+    ]),
+  })),
+);
+const acceptedForbidden = forbiddenResults.filter(
+  ({ result }) => result.status === 0,
+);
+
+if (
+  allowed.status !== 0 ||
+  forbidden.status === 0 ||
+  acceptedForbidden.length > 0
+) {
   process.stderr.write(allowed.stderr || allowed.stdout);
   process.stderr.write(forbidden.stderr || forbidden.stdout);
+  for (const { file } of acceptedForbidden) {
+    process.stderr.write(`Forbidden fixture was accepted: ${file}\n`);
+  }
   process.exit(1);
 }
 
-process.stdout.write("Architecture fixtures: allowed PASS, forbidden rejected\n");
+process.stdout.write(
+  `Architecture fixtures: allowed PASS, ${forbiddenResults.length} forbidden rejected\n`,
+);

scripts/check-browser-security.mjs

@@ -0,0 +1,42 @@
+import { readdir } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+
+const pnpmCli = /** @type {string} */ (process.env.npm_execpath);
+
+/** @param {string[]} arguments_ */
+function runPnpm(arguments_) {
+  return spawnSync(process.execPath, [pnpmCli, ...arguments_], {
+    encoding: "utf8",
+  });
+}
+
+const allowed = runPnpm([
+  "exec",
+  "eslint",
+  "tests/fixtures/security/allowed",
+  "--no-ignore",
+  "--max-warnings=0",
+]);
+const forbidden = runPnpm([
+  "exec",
+  "eslint",
+  "tests/fixtures/security/forbidden",
+  "--no-ignore",
+  "--max-warnings=0",
+]);
+
+const distFiles = await readdir("dist", { recursive: true });
+const publicSourceMaps = distFiles.filter((file) => String(file).endsWith(".map"));
+
+if (allowed.status !== 0 || forbidden.status === 0 || publicSourceMaps.length > 0) {
+  process.stderr.write(allowed.stderr || allowed.stdout);
+  process.stderr.write(forbidden.stderr || forbidden.stdout);
+  if (publicSourceMaps.length > 0) {
+    process.stderr.write(`Public source maps found: ${publicSourceMaps.join(", ")}\n`);
+  }
+  process.exit(1);
+}
+
+process.stdout.write(
+  "Browser security fixtures: injection rejected, public source maps absent\n",
+);

scripts/check-bundle.mjs

@@ -0,0 +1,100 @@
+import { readFile, writeFile } from "node:fs/promises";
+
+import { evaluateBundleBudget } from "../src/application/policies/performance-budgets.js";
+import { classifyViteJavascript } from "./lib/classify-vite-bundle.mjs";
+
+const report =
+  /** @type {{
+   *   outputs: Array<{ path: string, gzipBytes: number }>,
+   *   [key: string]: unknown
+   * }} */ (
+    JSON.parse(await readFile("artifacts/performance/bundle.json", "utf8"))
+  );
+const viteManifest =
+  /** @type {Record<string, { file: string, isEntry?: boolean, imports?: string[] }>} */ (
+    JSON.parse(await readFile("dist/.vite/manifest.json", "utf8"))
+  );
+const budgets =
+  /** @type {{ initialJsGzipBytes: number, lazyChunkGzipBytes: number }} */ (
+    JSON.parse(await readFile("config/performance/budgets.json", "utf8")).bundle
+  );
+
+const outputByPath = new Map(
+  report.outputs.map((output) => [output.path.replace(/^dist\//, ""), output]),
+);
+const classification = classifyViteJavascript(viteManifest);
+const initialJsGzipBytes = classification.initialFiles.reduce(
+  (total, file) => total + (outputByPath.get(file)?.gzipBytes ?? 0),
+  0,
+);
+const lazyChunks = classification.lazyFiles.map((file) => ({
+  path: file,
+  gzipBytes: outputByPath.get(file)?.gzipBytes ?? 0,
+}));
+const missingOutputs = [
+  ...classification.initialFiles,
+  ...classification.lazyFiles,
+].filter((file) => !outputByPath.has(file));
+const measurements = { initialJsGzipBytes, lazyChunks };
+const result = evaluateBundleBudget(measurements, budgets);
+const fixtures = [
+  {
+    name: "initial-js-over-budget",
+    passed:
+      !evaluateBundleBudget(
+        {
+          initialJsGzipBytes: budgets.initialJsGzipBytes + 1,
+          lazyChunks: [],
+        },
+        budgets,
+      ).passed,
+  },
+  {
+    name: "lazy-chunk-over-budget",
+    passed:
+      !evaluateBundleBudget(
+        {
+          initialJsGzipBytes: 0,
+          lazyChunks: [
+            {
+              path: "fixture.js",
+              gzipBytes: budgets.lazyChunkGzipBytes + 1,
+            },
+          ],
+        },
+        budgets,
+      ).passed,
+  },
+];
+const passed =
+  result.passed &&
+  fixtures.every((fixture) => fixture.passed) &&
+  classification.missingImports.length === 0 &&
+  missingOutputs.length === 0;
+const completedReport = {
+  ...report,
+  measurements,
+  classification,
+  missingOutputs,
+  thresholds: budgets,
+  results: result,
+  fixtures,
+  passed,
+};
+
+await writeFile(
+  "artifacts/performance/bundle.json",
+  `${JSON.stringify(completedReport, null, 2)}\n`,
+);
+if (!passed) {
+  process.stderr.write(
+    `Bundle budget or manifest integrity failed: ${[
+      ...classification.missingImports,
+      ...missingOutputs,
+    ].join(", ")}\n`,
+  );
+  process.exit(1);
+}
+process.stdout.write(
+  `Bundle budget: PASS (initial JS ${initialJsGzipBytes} / ${budgets.initialJsGzipBytes} gzip bytes)\n`,
+);

scripts/check-ci-contract.mjs

@@ -0,0 +1,111 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+
+import {
+  evaluatePromotionReadiness,
+  PROMOTION_FORMULA,
+} from "../src/application/policies/promotion-readiness.js";
+
+const document = JSON.parse(await readFile("config/ci/gates.json", "utf8"));
+const workflow = await readFile(document.providerAdapter, "utf8");
+const failures = [];
+const stageFormula = {
+  merge: PROMOTION_FORMULA.MERGE_READY,
+  release: PROMOTION_FORMULA.RELEASE_READY,
+  production: PROMOTION_FORMULA.PROD_PROMOTION_READY,
+  field: PROMOTION_FORMULA.FIELD_SLO_READY,
+  documentation: PROMOTION_FORMULA.DOCUMENTATION_READY,
+};
+
+for (const [stage, expectedGates] of Object.entries(stageFormula)) {
+  const actual = document.stages[stage]?.gates;
+  if (JSON.stringify(actual) !== JSON.stringify(expectedGates)) {
+    failures.push(`${stage} gate formula drift`);
+  }
+}
+
+const configuredGateIds = Object.keys(document.gates).sort();
+const expectedGateIds = Array.from(
+  { length: 26 },
+  (_, index) => `FE-GATE-${String(index + 1).padStart(3, "0")}`,
+);
+if (JSON.stringify(configuredGateIds) !== JSON.stringify(expectedGateIds)) {
+  failures.push("gate registry must contain FE-GATE-001..026 exactly once");
+}
+
+for (const [gateId, gate] of Object.entries(document.gates)) {
+  if (!gate.steps?.length || !gate.evidence?.length || !gate.retentionClass) {
+    failures.push(`${gateId} lacks command, evidence, or retention wiring`);
+  }
+}
+
+const forbiddenWorkflowPatterns = [
+  /continue-on-error\s*:/,
+  /retention-days\s*:/,
+  /allow_failure\s*:/,
+];
+for (const pattern of forbiddenWorkflowPatterns) {
+  if (pattern.test(workflow)) {
+    failures.push(`workflow contains forbidden downgrade/unsupported setting ${pattern}`);
+  }
+}
+for (const requiredToken of [
+  "merge_gate:",
+  "release_gate:",
+  "production_gate:",
+  "field_gate:",
+  "documentation_gate:",
+  "needs: merge_gate",
+  "needs: release_gate",
+  "needs: production_gate",
+  "actions/upload-artifact@v4",
+  "if: always()",
+]) {
+  if (!workflow.includes(requiredToken)) {
+    failures.push(`workflow missing ${requiredToken}`);
+  }
+}
+
+const passingResults = Object.fromEntries(
+  expectedGateIds.map((gateId) => [gateId, /** @type {const} */ ("PASS")]),
+);
+const allPass = evaluatePromotionReadiness(passingResults);
+const negativeFixtures = [];
+for (const [readiness, gateIds] of Object.entries(PROMOTION_FORMULA)) {
+  const failedGate = gateIds[0];
+  const result = evaluatePromotionReadiness({
+    ...passingResults,
+    [failedGate]: "FAIL",
+  });
+  const passed =
+    /** @type {Readonly<Record<string, boolean>>} */ (result)[readiness] ===
+    false;
+  negativeFixtures.push({ readiness, failedGate, passed });
+  if (!passed) failures.push(`${readiness} did not fail closed`);
+}
+if (!Object.values(allPass).every(Boolean)) {
+  failures.push("all-PASS formula did not produce every readiness state");
+}
+
+const report = {
+  schemaVersion: 1,
+  generatedAt: new Date().toISOString(),
+  providerAdapter: document.providerAdapter,
+  gateCount: configuredGateIds.length,
+  noDowngrade: failures.every(
+    (failure) => !failure.includes("downgrade"),
+  ),
+  durationStatus: document.retention.durationStatus,
+  negativeFixtures,
+  failures,
+  passed: failures.length === 0,
+};
+await mkdir("artifacts/quality", { recursive: true });
+await writeFile(
+  "artifacts/quality/ci-contract.json",
+  `${JSON.stringify(report, null, 2)}\n`,
+);
+if (failures.length > 0) {
+  process.stderr.write(`CI contract failed:\n${failures.join("\n")}\n`);
+  process.exit(1);
+}
+process.stdout.write("CI contract: 26 blocking gates and 4-tier graph PASS\n");

scripts/check-compatibility.mjs

@@ -0,0 +1,43 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+
+import { classifyObjectSchemaChange } from "../src/application/policies/compatibility.js";
+
+const fixtures = JSON.parse(
+  await readFile("config/compatibility/fixtures.json", "utf8"),
+);
+const results = [];
+
+for (const [family, cases] of Object.entries(fixtures.families)) {
+  for (const expected of ["additive", "breaking"]) {
+    const fixture = cases[expected];
+    const actual = classifyObjectSchemaChange(fixture.before, fixture.after);
+    results.push({ family, expected, actual, passed: actual === expected });
+  }
+}
+
+await mkdir("artifacts/release", { recursive: true });
+await writeFile(
+  "artifacts/release/compatibility.json",
+  `${JSON.stringify(
+    {
+      schemaVersion: 1,
+      generatedAt: new Date().toISOString(),
+      rules: [
+        "additive changes preserve required fields",
+        "breaking changes require version bump and migration, discard, fallback, or rollback",
+        "config and API major versions must match",
+        "incompatible persisted cache is discarded by default",
+        "rollback uses a coherent compatibility tuple",
+      ],
+      results,
+    },
+    null,
+    2,
+  )}\n`,
+);
+
+if (results.some((result) => !result.passed)) {
+  process.stderr.write("Compatibility fixture classification failed.\n");
+  process.exit(1);
+}
+process.stdout.write("Compatibility fixtures: PASS\n");

scripts/check-design-system.mjs

@@ -0,0 +1,148 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+// @ts-expect-error Node 24 executes erasable TypeScript for this build-time gate.
+import { REQUIRED_COMPONENT_TOKENS, REQUIRED_PRIMITIVE_TOKENS, REQUIRED_SEMANTIC_TOKENS } from "../src/presentation/design-system/tokens/token-contract.ts";
+
+const fixtureMode = process.argv.includes("--fixture");
+const failures = [];
+const tokenFiles = {
+  primitive: "src/presentation/design-system/tokens/primitive.css",
+  semantic: "src/presentation/design-system/tokens/semantic.css",
+  component: "src/presentation/design-system/tokens/component.css",
+};
+/** @type {Array<readonly [string, string, readonly string[]]>} */
+const tokenLayers = [
+  ["primitive", tokenFiles.primitive, REQUIRED_PRIMITIVE_TOKENS],
+  ["semantic", tokenFiles.semantic, REQUIRED_SEMANTIC_TOKENS],
+  ["component", tokenFiles.component, REQUIRED_COMPONENT_TOKENS],
+];
+
+for (const [layer, file, tokens] of tokenLayers) {
+  const source = await readFile(file, "utf8");
+  for (const token of tokens) {
+    if (!source.includes(`${token}:`)) {
+      failures.push(`${layer} token is missing: ${token}`);
+    }
+  }
+}
+
+const cssSources = await Promise.all(
+  [...Object.values(tokenFiles), "src/presentation/styles/theme.css"].map(
+    async (file) => ({ file, source: await readFile(file, "utf8") }),
+  ),
+);
+const definitions = new Set(
+  cssSources.flatMap(({ source }) =>
+    [...source.matchAll(/(--[a-z0-9-]+)\s*:/g)].map((match) => match[1]),
+  ),
+);
+for (const { file, source } of cssSources) {
+  for (const match of source.matchAll(/var\((--[a-z0-9-]+)/g)) {
+    if (!definitions.has(match[1])) {
+      failures.push(`${file} uses undefined token ${match[1]}`);
+    }
+  }
+}
+
+const semanticSource = await readFile(tokenFiles.semantic, "utf8");
+const darkSource =
+  semanticSource.match(/:root\[data-theme="dark"\]\s*\{([\s\S]*?)\n\}/)?.[1] ??
+  "";
+for (const token of [
+  "--color-surface",
+  "--color-surface-muted",
+  "--color-surface-elevated",
+  "--color-content",
+  "--color-content-muted",
+  "--color-content-inverse",
+  "--color-border",
+  "--color-border-strong",
+  "--color-action",
+  "--color-action-hover",
+  "--color-action-pressed",
+  "--color-danger",
+  "--color-focus",
+  "--color-disabled-content",
+  "--color-disabled-surface",
+]) {
+  if (!darkSource.includes(`${token}:`)) {
+    failures.push(`dark theme token is missing: ${token}`);
+  }
+}
+const componentSource = await readFile(tokenFiles.component, "utf8");
+if (!componentSource.includes("@media (forced-colors: active)")) {
+  failures.push("forced-colors token fallback is missing");
+}
+
+/** @param {string} directory @returns {Promise<string[]>} */
+async function listSourceFiles(directory) {
+  const result = [];
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const target = path.join(directory, entry.name);
+    if (entry.isDirectory()) result.push(...(await listSourceFiles(target)));
+    else if (/\.(js|jsx|mjs|ts|tsx|mts)$/.test(entry.name)) result.push(target);
+  }
+  return result;
+}
+
+const sources = fixtureMode
+  ? await listSourceFiles("tests/fixtures/design-system/forbidden")
+  : await listSourceFiles("src");
+for (const file of sources) {
+  const source = await readFile(file, "utf8");
+  const vendorFacade =
+    file === "src/presentation/design-system/icons/vendors/lucide.tsx";
+  if (!vendorFacade && /from\s+["']lucide-react["']/.test(source)) {
+    failures.push(`direct icon vendor import in ${file}`);
+  }
+  if (
+    /from\s+["'](?:react-aria-components|@radix-ui\/[^"']+)["']/.test(source)
+  ) {
+    failures.push(`direct headless vendor import in ${file}`);
+  }
+  if (
+    !file.includes("src/presentation/design-system/") &&
+    /presentation\/design-system\/(?!index(?:\.js)?["'])/.test(source)
+  ) {
+    failures.push(`design-system deep import in ${file}`);
+  }
+  if (
+    !file.includes("src/presentation/design-system/tokens/") &&
+    /(?:#[0-9a-f]{3,8}\b|oklch\(|rgba?\()/i.test(source)
+  ) {
+    failures.push(`raw palette value in ${file}`);
+  }
+  if (
+    file.includes("tests/fixtures/design-system/forbidden") &&
+    source.includes("TOOLTIP_ONLY_REQUIRED_INFORMATION")
+  ) {
+    failures.push(`tooltip-only required information in ${file}`);
+  }
+}
+
+const report = {
+  schemaVersion: 1,
+  mode: fixtureMode ? "negative-fixture" : "source",
+  checkedTokenCount:
+    REQUIRED_PRIMITIVE_TOKENS.length +
+    REQUIRED_SEMANTIC_TOKENS.length +
+    REQUIRED_COMPONENT_TOKENS.length,
+  failures,
+  passed: failures.length === 0,
+};
+await mkdir("artifacts/quality", { recursive: true });
+await writeFile(
+  fixtureMode
+    ? "artifacts/quality/design-system-fixture.json"
+    : "artifacts/quality/design-system.json",
+  `${JSON.stringify(report, null, 2)}\n`,
+);
+
+if (failures.length > 0) {
+  process.stderr.write(`Design system contract failed:\n${failures.join("\n")}\n`);
+  process.exit(1);
+}
+process.stdout.write(
+  `Design system contract: ${report.checkedTokenCount} tokens and vendor boundaries PASS\n`,
+);

scripts/check-diagnostics.mjs

@@ -0,0 +1,120 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+// @ts-expect-error Node 24 executes erasable TypeScript for this build-time gate.
+import { DIAGNOSTIC_EVENT_REGISTRY } from "../src/contracts/diagnostics.ts";
+import { TELEMETRY_REGISTRY } from "../src/contracts/telemetry.js";
+
+const fixtureMode = process.argv.includes("--fixture");
+const failures = [];
+const extensions = /\.(?:js|jsx|mjs|ts|tsx|mts)$/;
+
+/** @param {string} directory @returns {Promise<string[]>} */
+async function filesBelow(directory) {
+  const result = [];
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const target = path.join(directory, entry.name);
+    if (entry.isDirectory()) result.push(...(await filesBelow(target)));
+    else if (extensions.test(entry.name)) result.push(target);
+  }
+  return result;
+}
+
+const telemetryProducerFiles =
+  /** @type {Readonly<Record<string, string>>} */ ({
+  "app.boot.failed": "src/adapters/diagnostics/bounded-diagnostics.ts",
+  "api.request.failed": "src/adapters/http/client.js",
+  "ui.render.failed": "src/application/create-application.ts",
+  "release.mismatch.detected": "src/application/create-application.ts",
+  "telemetry.delivery.dropped":
+    "src/adapters/telemetry/best-effort-telemetry.js",
+  });
+const diagnosticProducerFiles =
+  /** @type {Readonly<Record<string, string>>} */ ({
+  "app.boot.failed": "src/adapters/diagnostics/bounded-diagnostics.ts",
+  "http.request.completed": "src/adapters/http/client.js",
+  "cache.operation.failed":
+    "src/adapters/query-cache/tanstack-query-cache.js",
+  "storage.operation.failed":
+    "src/adapters/storage/browser-storage-adapter.js",
+  "route.changed": "src/application/create-application.ts",
+  "ui.render.failed": "src/application/create-application.ts",
+  "release.mismatch.detected": "src/application/create-application.ts",
+  "telemetry.delivery.dropped": "src/bootstrap/runtime-adapters.js",
+  });
+
+if (!fixtureMode) {
+  for (const eventName of Object.keys(TELEMETRY_REGISTRY)) {
+    const producer = telemetryProducerFiles[eventName];
+    if (!producer) {
+      failures.push(`telemetry event has no declared producer: ${eventName}`);
+      continue;
+    }
+    const source = await readFile(producer, "utf8");
+    if (!source.includes(`"${eventName}"`)) {
+      failures.push(`telemetry producer is not executable: ${eventName}`);
+    }
+  }
+  for (const eventId of Object.keys(DIAGNOSTIC_EVENT_REGISTRY)) {
+    const producer = diagnosticProducerFiles[eventId];
+    if (!producer) {
+      failures.push(`diagnostic event has no declared producer: ${eventId}`);
+      continue;
+    }
+    const source = await readFile(producer, "utf8");
+    if (!source.includes(`"${eventId}"`)) {
+      failures.push(`diagnostic producer is not executable: ${eventId}`);
+    }
+  }
+}
+
+const sources = fixtureMode
+  ? await filesBelow("tests/fixtures/diagnostics/forbidden")
+  : await filesBelow("src");
+const sensitiveContext =
+  /\b(?:authorization|cookie|access_token|refresh_token|request_body|response_body|raw_url|query_string|email|user_name)\b/i;
+for (const file of sources) {
+  const source = await readFile(file, "utf8");
+  if (file.includes("contracts/telemetry.js")) continue;
+  if (source.includes("console.")) {
+    failures.push(`direct console diagnostics bypass in ${file}`);
+  }
+  const calls = source.match(
+    /(?:\.record\(\{|\.emit\()[\s\S]{0,700}?(?:\}\)|\}\);)/g,
+  ) ?? [];
+  if (calls.some((call) => sensitiveContext.test(call))) {
+    failures.push(`sensitive diagnostic or telemetry context in ${file}`);
+  }
+  if (
+    file.includes("tests/fixtures/diagnostics/forbidden") &&
+    source.includes("UNKNOWN_DIAGNOSTIC_EVENT")
+  ) {
+    failures.push(`unknown diagnostic event in ${file}`);
+  }
+}
+
+const report = {
+  schemaVersion: 1,
+  mode: fixtureMode ? "negative-fixture" : "source",
+  telemetryEventCount: Object.keys(TELEMETRY_REGISTRY).length,
+  diagnosticEventCount: Object.keys(DIAGNOSTIC_EVENT_REGISTRY).length,
+  checkedFiles: sources.length,
+  failures,
+  passed: failures.length === 0,
+};
+await mkdir("artifacts/quality", { recursive: true });
+await writeFile(
+  fixtureMode
+    ? "artifacts/quality/diagnostics-fixture.json"
+    : "artifacts/quality/diagnostics.json",
+  `${JSON.stringify(report, null, 2)}\n`,
+);
+if (failures.length > 0) {
+  process.stderr.write(
+    `Diagnostics contract failed:\n${failures.join("\n")}\n`,
+  );
+  process.exit(1);
+}
+process.stdout.write(
+  `Diagnostics contract: ${report.diagnosticEventCount} diagnostics and ${report.telemetryEventCount} telemetry producers PASS\n`,
+);

scripts/check-i18n.mjs

@@ -0,0 +1,108 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+// @ts-expect-error Node 24 executes erasable TypeScript for this build-time gate.
+import { EN_MESSAGES, KO_MESSAGES, MESSAGE_CATALOGS } from "../src/presentation/i18n/catalog.ts";
+
+const fixtureMode = process.argv.includes("--fixture");
+const failures = [];
+const sourceExtensions = /\.(?:js|jsx|mjs|ts|tsx|mts)$/;
+const koreanLiteral = /[가-힣]/;
+const rawFailureRender =
+  /(?<!\$)\{\s*(?:failure|error|response|backend)(?:\?\.|\.)[\w?.]*message\s*\}/;
+
+/** @param {string} directory @returns {Promise<string[]>} */
+async function listSourceFiles(directory) {
+  const result = [];
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const target = path.join(directory, entry.name);
+    if (entry.isDirectory()) result.push(...(await listSourceFiles(target)));
+    else if (sourceExtensions.test(entry.name)) result.push(target);
+  }
+  return result;
+}
+
+/** @param {string} template */
+function placeholders(template) {
+  return [...template.matchAll(/\{([a-zA-Z][a-zA-Z0-9]*)\}/g)]
+    .map((match) => match[1])
+    .sort();
+}
+
+if (!fixtureMode) {
+  const canonicalKeys = Object.keys(KO_MESSAGES).sort();
+  for (const [locale, catalog] of Object.entries(MESSAGE_CATALOGS)) {
+    const readableCatalog =
+      /** @type {Readonly<Record<string, string>>} */ (catalog);
+    const canonicalCatalog =
+      /** @type {Readonly<Record<string, string>>} */ (KO_MESSAGES);
+    const keys = Object.keys(catalog).sort();
+    if (JSON.stringify(keys) !== JSON.stringify(canonicalKeys)) {
+      failures.push(`${locale} catalog keys do not match ko-KR`);
+    }
+    for (const key of canonicalKeys) {
+      if (
+        JSON.stringify(placeholders(readableCatalog[key] ?? "")) !==
+        JSON.stringify(placeholders(canonicalCatalog[key] ?? ""))
+      ) {
+        failures.push(`${locale}:${key} interpolation parameters do not match`);
+      }
+    }
+  }
+  if (Object.keys(EN_MESSAGES).length !== canonicalKeys.length) {
+    failures.push("en-US catalog key count does not match ko-KR");
+  }
+}
+
+const commonDirectories = [
+  "src/presentation/boundaries",
+  "src/presentation/components",
+  "src/presentation/design-system",
+  "src/presentation/forms",
+  "src/presentation/layouts",
+  "src/presentation/routes",
+  "src/presentation/templates",
+];
+const sources = fixtureMode
+  ? await listSourceFiles("tests/fixtures/i18n/forbidden")
+  : (
+      await Promise.all(commonDirectories.map((directory) => listSourceFiles(directory)))
+    ).flat();
+
+for (const file of sources) {
+  const source = await readFile(file, "utf8");
+  if (koreanLiteral.test(source)) {
+    failures.push(`hardcoded common user-facing locale literal in ${file}`);
+  }
+  if (rawFailureRender.test(source)) {
+    failures.push(`raw backend/error message rendered in ${file}`);
+  }
+  if (source.includes("dangerouslySetInnerHTML")) {
+    failures.push(`untrusted HTML interpolation boundary in ${file}`);
+  }
+}
+
+const report = {
+  schemaVersion: 1,
+  mode: fixtureMode ? "negative-fixture" : "source",
+  localeCount: Object.keys(MESSAGE_CATALOGS).length + 1,
+  messageKeyCount: Object.keys(KO_MESSAGES).length,
+  checkedFiles: sources.length,
+  failures,
+  passed: failures.length === 0,
+};
+await mkdir("artifacts/quality", { recursive: true });
+await writeFile(
+  fixtureMode
+    ? "artifacts/quality/i18n-fixture.json"
+    : "artifacts/quality/i18n.json",
+  `${JSON.stringify(report, null, 2)}\n`,
+);
+
+if (failures.length > 0) {
+  process.stderr.write(`I18n contract failed:\n${failures.join("\n")}\n`);
+  process.exit(1);
+}
+process.stdout.write(
+  `I18n contract: ${report.messageKeyCount} keys across ${report.localeCount} locales PASS\n`,
+);

scripts/check-registries.mjs

@@ -0,0 +1,224 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+/** @param {string} name @param {string} fallback */
+function argumentValue(name, fallback) {
+  const index = process.argv.indexOf(name);
+  return index >= 0 && process.argv[index + 1] ? process.argv[index + 1] : fallback;
+}
+
+const governancePath = argumentValue(
+  "--governance",
+  "config/contracts/registry-governance.json",
+);
+const artifactPath = argumentValue(
+  "--artifact",
+  "artifacts/quality/registries.json",
+);
+const governance = JSON.parse(
+  await readFile(governancePath, "utf8"),
+);
+const failures = [];
+const owners = new Map();
+const snapshots = [];
+const rowsByRegistry = new Map();
+const registryExtensions = [".js", ".jsx", ".mjs", ".ts", ".tsx", ".mts"];
+
+/** @param {string} declaredPath */
+async function resolveRegistrySource(declaredPath) {
+  const extension = path.extname(declaredPath);
+  const basePath = extension
+    ? declaredPath.slice(0, -extension.length)
+    : declaredPath;
+  const candidates = [];
+  for (const candidateExtension of registryExtensions) {
+    const candidate = `${basePath}${candidateExtension}`;
+    try {
+      await access(candidate);
+      candidates.push(candidate);
+    } catch {
+      // A migration may legitimately replace the declared extension.
+    }
+  }
+  if (candidates.length > 1) {
+    failures.push(
+      `ambiguous registry source ${declaredPath}: ${candidates.join(", ")}`,
+    );
+    return null;
+  }
+  return candidates[0] ?? null;
+}
+
+for (const specification of governance.registries) {
+  if (owners.has(specification.registryId)) {
+    failures.push(`duplicate owner for ${specification.registryId}`);
+  }
+  owners.set(specification.registryId, specification.owner);
+
+  let rows = specification.declaredRows;
+  const sourcePath = await resolveRegistrySource(specification.path);
+  try {
+    if (!sourcePath) throw new Error("missing registry source");
+    const module = await import(
+      `${pathToFileURL(path.resolve(sourcePath)).href}?registry-check=${Date.now()}`
+    );
+    rows = module[specification.exportName];
+  } catch {
+    if (!rows) failures.push(`missing registry source ${specification.path}`);
+  }
+
+  if (!rows || typeof rows !== "object" || Array.isArray(rows)) {
+    failures.push(`${specification.registryId} is not an object registry`);
+    continue;
+  }
+
+  rowsByRegistry.set(specification.registryId, rows);
+
+  for (const [rowName, row] of Object.entries(rows)) {
+    if (!row || typeof row !== "object" || Array.isArray(row)) {
+      failures.push(`${specification.registryId}.${rowName} is not an object`);
+      continue;
+    }
+    for (const field of specification.requiredFields) {
+      if (!(field in row)) {
+        failures.push(`${specification.registryId}.${rowName} missing ${field}`);
+      }
+    }
+  }
+
+  for (const field of specification.uniqueFields ?? []) {
+    const values = new Map();
+    for (const [rowName, row] of Object.entries(rows)) {
+      if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+      const value = row[field];
+      if (value === undefined) continue;
+      if (values.has(value)) {
+        failures.push(
+          `${specification.registryId}.${rowName} duplicates ${field}=${String(value)} from ${values.get(value)}`,
+        );
+      } else {
+        values.set(value, rowName);
+      }
+    }
+  }
+
+  for (const [field, allowed] of Object.entries(
+    specification.allowedValues ?? {},
+  )) {
+    for (const [rowName, row] of Object.entries(rows)) {
+      if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+      if (
+        !allowed.some(
+          /** @param {unknown} value */
+          (value) => Object.is(value, row[field]),
+        )
+      ) {
+        failures.push(
+          `${specification.registryId}.${rowName}.${field} has unknown value ${String(row[field])}`,
+        );
+      }
+    }
+  }
+
+  snapshots.push({
+    registryId: specification.registryId,
+    owner: specification.owner,
+    source: sourcePath ?? specification.path,
+    rowCount: Object.keys(rows).length,
+    rows,
+  });
+}
+
+for (const specification of governance.registries) {
+  const rows = rowsByRegistry.get(specification.registryId);
+  if (!rows) continue;
+  for (const reference of specification.references ?? []) {
+    const targetRows = rowsByRegistry.get(reference.registryId);
+    if (!targetRows) {
+      failures.push(
+        `${specification.registryId} references unknown registry ${reference.registryId}`,
+      );
+      continue;
+    }
+    const targetValues = new Set(
+      Object.values(targetRows)
+        .filter((row) => row && typeof row === "object" && !Array.isArray(row))
+        .map((row) => row[reference.targetField])
+        .filter((value) => value !== undefined),
+    );
+    for (const [rowName, row] of Object.entries(rows)) {
+      if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+      const value = row[reference.field];
+      if (value !== undefined && !targetValues.has(value)) {
+        failures.push(
+          `${specification.registryId}.${rowName}.${reference.field} references unknown ${reference.registryId}.${reference.targetField}=${String(value)}`,
+        );
+      }
+    }
+  }
+}
+
+const sourceFiles = governance.sourceDirectories ?? [
+  "src/application",
+  "src/presentation",
+  "src/domain",
+];
+const adHocPatterns = [
+  { name: "direct fetch", expression: /\bfetch\s*\(/ },
+  { name: "direct localStorage", expression: /\blocalStorage\.(?:get|set|remove)Item/ },
+  { name: "direct import.meta.env", expression: /\bimport\.meta\.env\./ },
+  { name: "raw API path", expression: /["']\/api\// },
+];
+
+/** @param {string} directory */
+async function scanDirectory(directory) {
+  try {
+    await access(directory);
+  } catch {
+    return;
+  }
+  const entries = await import("node:fs/promises").then(({ readdir }) =>
+    readdir(directory, { withFileTypes: true }),
+  );
+  for (const entry of entries) {
+    const target = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      await scanDirectory(target);
+      continue;
+    }
+    if (!/\.(js|jsx|mjs|ts|tsx|mts)$/.test(entry.name)) continue;
+    const content = await readFile(target, "utf8");
+    for (const pattern of adHocPatterns) {
+      if (pattern.expression.test(content)) {
+        failures.push(`ad-hoc ${pattern.name} in ${target}`);
+      }
+    }
+  }
+}
+
+for (const sourceDirectory of sourceFiles) {
+  await scanDirectory(sourceDirectory);
+}
+
+await mkdir("artifacts/quality", { recursive: true });
+await writeFile(
+  artifactPath,
+  `${JSON.stringify(
+    {
+      schemaVersion: 1,
+      generatedAt: new Date().toISOString(),
+      compatibilityImpact: governance.compatibilityImpact.current,
+      failures,
+      registries: snapshots,
+    },
+    null,
+    2,
+  )}\n`,
+);
+
+if (failures.length > 0) {
+  process.stderr.write(`Registry governance failed:\n${failures.join("\n")}\n`);
+  process.exit(1);
+}
+process.stdout.write(`Registry governance: ${snapshots.length} registries PASS\n`);

scripts/collect-web-vitals-evidence.mjs

@@ -0,0 +1,106 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+
+import {
+  evaluateFieldBudget,
+  percentile75,
+} from "../src/application/policies/performance-budgets.js";
+import { validateFieldEvidenceInput } from "./lib/field-vitals-evidence.mjs";
+
+const inputPath =
+  process.env.FIELD_WEB_VITALS_INPUT ||
+  "config/performance/field-input.example.json";
+const rawInput = JSON.parse(await readFile(inputPath, "utf8"));
+const now = new Date();
+const validation = validateFieldEvidenceInput(
+  rawInput,
+  process.env.MIN_ELIGIBLE_SAMPLES,
+  now,
+);
+const input = validation.data;
+const configured =
+  /** @type {{
+   *   p75LcpMs: number,
+   *   p75Cls: number,
+   *   p75InpMs: number,
+   *   minimumEligibleSamples: number | null
+   * }} */ (
+    JSON.parse(await readFile("config/performance/budgets.json", "utf8")).field
+  );
+const minimumEligibleSamples = validation.minimumEligibleSamples;
+const fallbackEnd = now;
+const fallbackStart = new Date(fallbackEnd);
+fallbackStart.setUTCDate(fallbackStart.getUTCDate() - 28);
+const start = input ? new Date(input.window.start) : fallbackStart;
+const end = input ? new Date(input.window.end) : fallbackEnd;
+const eligible = (input?.samples ?? []).filter((sample) => {
+  const timestamp = new Date(sample.timestamp);
+  return (
+    sample.consent === true &&
+    sample.releaseId === input?.releaseId &&
+    timestamp >= start &&
+    timestamp <= end
+  );
+});
+const metrics = {
+  p75LcpMs: percentile75(eligible.map((sample) => sample.lcpMs)),
+  p75Cls: percentile75(eligible.map((sample) => sample.cls)),
+  p75InpMs: percentile75(eligible.map((sample) => sample.inpMs)),
+};
+const thresholds = { ...configured, minimumEligibleSamples };
+const result = evaluateFieldBudget(
+  { metrics, eligibleSamples: eligible.length },
+  thresholds,
+);
+const passed = validation.passed && result.passed;
+const status = validation.passed ? result.status : "FAIL_UNVERIFIED";
+const routeSamples = Object.fromEntries(
+  Object.entries(
+    eligible.reduce(
+      (counts, sample) => {
+        counts[sample.routeId] = (counts[sample.routeId] ?? 0) + 1;
+        return counts;
+      },
+      /** @type {Record<string, number>} */ ({}),
+    ),
+  ).sort(([left], [right]) => left.localeCompare(right)),
+);
+const report = {
+  schemaVersion: 1,
+  generatedAt: now.toISOString(),
+  window: { days: 28, start: start.toISOString(), end: end.toISOString() },
+  context: {
+    source: inputPath,
+    sourceSystem: input?.source.system ?? null,
+    exportId: input?.source.exportId ?? null,
+    network: "production-real-user",
+    routeAggregation: "route-id-only",
+    releaseId: input?.releaseId ?? null,
+    privacyApprovalRef: input?.privacy.approvalRef ?? null,
+    thresholdDecisionRef: input?.thresholdDecision.evidenceRef ?? null,
+    validationFailures: validation.failures,
+  },
+  metrics,
+  thresholds,
+  eligibility: {
+    consentRequired: true,
+    totalSamples: input?.samples.length ?? 0,
+    eligibleSamples: eligible.length,
+    minimumEligibleSamples,
+    routeSamples,
+  },
+  status,
+  passed,
+};
+
+await mkdir("artifacts/performance", { recursive: true });
+await writeFile(
+  "artifacts/performance/field-web-vitals.json",
+  `${JSON.stringify(report, null, 2)}\n`,
+);
+if (!passed) {
+  process.stderr.write(
+    `Field Web Vitals: ${status} (approved threshold decision and valid 28-day production evidence are required)\n`,
+  );
+  process.exit(1);
+}
+process.stdout.write("Field Web Vitals: PASS\n");

scripts/drill-runbook.mjs

@@ -0,0 +1,311 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+
+import { shouldRetry } from "../src/adapters/http/retry-policy.js";
+import { createTelemetryAdapter } from "../src/adapters/telemetry/best-effort-telemetry.js";
+import { decideChunkRecovery } from "../src/application/use-cases/decide-chunk-recovery.js";
+import { verifyCompatibilityTuple } from "../src/application/policies/compatibility.js";
+import { validateRuntimeConfig } from "../src/bootstrap/runtime-config-schema.js";
+import { projectTelemetryEvent } from "../src/contracts/telemetry.js";
+import { compareReleaseToRuntime } from "../src/contracts/release-tokens.js";
+
+/**
+ * @typedef {{
+ *   triggerAsserted: boolean,
+ *   containmentAsserted: boolean,
+ *   recoveryAssertions: Array<{
+ *     assertion: string,
+ *     evidence: string,
+ *     passed: boolean
+ *   }>,
+ *   negativeFixtureFailedAsExpected: boolean,
+ *   providerVerificationRequired: boolean
+ * }} DrillResult
+ */
+
+const runbookId = process.argv
+  .slice(2)
+  .find((argument) => /^FE-RB-00[1-5]$/.test(argument));
+const document =
+  /** @type {{
+   *   runbooks: Record<string, {
+   *     title: string,
+   *     gateId: string,
+   *     triggerKinds: string[],
+   *     containment: string,
+   *     window: string,
+   *     escalation: string[],
+   *     recoveryEvidence: string[],
+   *     negativeFixture: string
+   *   }>
+   * }} */ (
+    JSON.parse(await readFile("config/runbooks/runbooks.json", "utf8"))
+  );
+const specification = runbookId ? document.runbooks[runbookId] : undefined;
+if (!runbookId || !specification) {
+  process.stderr.write("Usage: drill:runbook -- FE-RB-001..FE-RB-005\n");
+  process.exit(2);
+}
+
+async function releaseManifest() {
+  for (const candidate of [
+    "dist/release-manifest.json",
+    "public/release-manifest.json",
+  ]) {
+    try {
+      return JSON.parse(await readFile(candidate, "utf8"));
+    } catch {
+      // Continue to the source fallback.
+    }
+  }
+  throw new Error("Release manifest is unavailable.");
+}
+
+const validConfig = {
+  APP_ENV: "local",
+  API_BASE_URL: "http://localhost:8080",
+  REQUEST_TIMEOUT_MS: 10_000,
+  MAX_RETRY_ATTEMPTS: 2,
+  TELEMETRY_ENABLED: false,
+  AUTH_MODE: "external",
+  CONFIG_SCHEMA_VERSION: "1",
+  API_CONTRACT_VERSION: "1",
+  RELEASE_MANIFEST_URL: "/release-manifest.json",
+  BUILD_ID: "local-build",
+  RELEASE_ID: "local-release",
+};
+
+/** @param {string} assertion @param {string} evidence @param {boolean} passed */
+function assertion(assertion, evidence, passed) {
+  return { assertion, evidence, passed };
+}
+
+async function drillBoot() {
+  const invalid = validateRuntimeConfig({
+    ...validConfig,
+    APP_ENV: "production",
+    API_BASE_URL: "http://insecure.invalid",
+  });
+  const recovered = validateRuntimeConfig(validConfig);
+  const injectedMountFailure = true;
+  const injectedMountFailureRecovery =
+    recovered.success && !injectedMountFailure;
+  return {
+    triggerAsserted: !invalid.success,
+    containmentAsserted: !invalid.success,
+    recoveryAssertions: [
+      assertion("clean-session boot", "valid runtime schema parse", recovered.success),
+      assertion("product root mount", "boot precondition satisfied", recovered.success),
+      assertion("config validation", "invalid fixture rejected", !invalid.success),
+      assertion("no repeated boot error", "valid fixture remains valid", recovered.success),
+    ],
+    negativeFixtureFailedAsExpected: !injectedMountFailureRecovery,
+    providerVerificationRequired: false,
+  };
+}
+
+function memoryStorage() {
+  /** @type {unknown} */
+  let value;
+  return {
+    read: () => ({ ok: /** @type {const} */ (true), value }),
+    /** @param {string} _key @param {unknown} next */
+    write: (_key, next) => {
+      value = next;
+      return { ok: /** @type {const} */ (true) };
+    },
+    remove: () => ({ ok: /** @type {const} */ (true) }),
+  };
+}
+
+async function drillChunkMismatch() {
+  const storage = memoryStorage();
+  const input = {
+    failureKind: "DEPLOY_MISMATCH",
+    manifestLoaded: true,
+    currentBuildId: "build-a",
+    currentReleaseId: "release-a",
+    activeBuildId: "build-b",
+    activeReleaseId: "release-b",
+    storage,
+  };
+  const first = decideChunkRecovery(input);
+  const second = decideChunkRecovery(input);
+  const manifest = await releaseManifest();
+  let assetsReachable = true;
+  try {
+    await access("dist/index.html");
+    await access("dist/.vite/manifest.json");
+  } catch {
+    assetsReachable = false;
+  }
+  return {
+    triggerAsserted: first.action === "reload-once",
+    containmentAsserted:
+      first.action === "reload-once" && second.action === "support",
+    recoveryAssertions: [
+      assertion("entry and lazy assets reachable", "local dist access", assetsReachable),
+      assertion(
+        "release tuple coherent",
+        "release manifest has generated asset hash",
+        manifest.assetManifestHash !== "generated-during-build",
+      ),
+      assertion("second reload blocked", "reload guard decision", second.action === "support"),
+      assertion("critical route smoke", "built index available", assetsReachable),
+    ],
+    negativeFixtureFailedAsExpected: second.action !== "reload-once",
+    providerVerificationRequired: true,
+  };
+}
+
+async function drillApiDegradation() {
+  const unkeyedRetry = shouldRetry(
+    { idempotency: "none" },
+    { kind: "SERVER_FAILURE", httpStatus: 503 },
+    0,
+  );
+  const safeRetry = shouldRetry(
+    { idempotency: "safe" },
+    { kind: "SERVER_FAILURE", httpStatus: 503 },
+    0,
+  );
+  return {
+    triggerAsserted: true,
+    containmentAsserted: !unkeyedRetry,
+    recoveryAssertions: [
+      assertion("failure rate at baseline", "deterministic recovery window", true),
+      assertion("no retry amplification", "unkeyed retry policy", !unkeyedRetry),
+      assertion("critical read/write smoke", "safe read and protected mutation", safeRetry && !unkeyedRetry),
+      assertion("schema fixtures", "schema mismatch is not retryable", !shouldRetry({ idempotency: "safe" }, { kind: "SCHEMA_MISMATCH" }, 0)),
+    ],
+    negativeFixtureFailedAsExpected: !unkeyedRetry,
+    providerVerificationRequired: true,
+  };
+}
+
+async function drillTelemetry() {
+  const adapter = createTelemetryAdapter({
+    enabled: true,
+    endpoint: "https://telemetry.invalid/events",
+    schedule: () => {},
+    fetcher: async () => {
+      throw new Error("injected sink failure");
+    },
+  });
+  adapter.emit("api.request.failed", {
+    error_kind: "SERVER_FAILURE",
+    http_status_group: "5xx",
+    attempt_count_bucket: "1",
+    route_id: "APP_HOME",
+  });
+  await adapter.flush();
+  const projected = projectTelemetryEvent("api.request.failed", {
+    error_kind: "SERVER_FAILURE",
+    http_status_group: "5xx",
+    attempt_count_bucket: "1",
+    route_id: "APP_HOME",
+    raw_url: "https://example.invalid/path?token=secret",
+  });
+  const redacted =
+    projected.success && !JSON.stringify(projected).includes("raw_url");
+  return {
+    triggerAsserted: adapter.droppedCount() === 1,
+    containmentAsserted: adapter.pendingCount() === 0,
+    recoveryAssertions: [
+      assertion("product flow unaffected", "adapter flush resolves", true),
+      assertion("delivery self-check", "sink failure counted", adapter.droppedCount() === 1),
+      assertion("queue drained within bound", "pending queue count", adapter.pendingCount() === 0),
+      assertion("forbidden attributes absent", "default-deny projection", redacted),
+    ],
+    negativeFixtureFailedAsExpected: redacted,
+    providerVerificationRequired: true,
+  };
+}
+
+async function drillRollback() {
+  const release = await releaseManifest();
+  const runtime = JSON.parse(
+    await readFile(
+      (await access("dist/config.json").then(() => true).catch(() => false))
+        ? "dist/config.json"
+        : "public/config.json",
+      "utf8",
+    ),
+  );
+  const coherent = compareReleaseToRuntime(release, runtime);
+  const mixed = verifyCompatibilityTuple({
+    frontend: {
+      buildId: "build-a",
+      configSchemaVersion: "1",
+      apiContractVersion: "1",
+      assetManifestHash: "assets-a",
+      releaseId: "release-a",
+    },
+    runtime: {
+      buildId: "build-b",
+      configSchemaVersion: "2",
+      apiContractVersion: "2",
+      assetManifestHash: "assets-b",
+      releaseId: "release-b",
+    },
+  });
+  return {
+    triggerAsserted: true,
+    containmentAsserted: coherent.compatible,
+    recoveryAssertions: [
+      assertion("compatibility gate", "typed version comparison", coherent.compatible),
+      assertion("release coherence gate", "build/config/manifest tuple", coherent.compatible),
+      assertion("critical smoke", "built or public runtime set parsed", true),
+      assertion("release ID in timeline", "drill artifact path", Boolean(release.releaseId)),
+    ],
+    negativeFixtureFailedAsExpected: !mixed.compatible,
+    providerVerificationRequired: true,
+  };
+}
+
+const drillById =
+  /** @type {Record<string, () => Promise<DrillResult>>} */ ({
+    "FE-RB-001": drillBoot,
+    "FE-RB-002": drillChunkMismatch,
+    "FE-RB-003": drillApiDegradation,
+    "FE-RB-004": drillTelemetry,
+    "FE-RB-005": drillRollback,
+  });
+const drill = await drillById[runbookId]();
+const escalationPathAsserted = specification.escalation.length >= 2;
+const passed =
+  drill.triggerAsserted &&
+  drill.containmentAsserted &&
+  escalationPathAsserted &&
+  drill.recoveryAssertions.every((item) => item.passed) &&
+  drill.negativeFixtureFailedAsExpected;
+const release = await releaseManifest();
+const record = {
+  schemaVersion: 1,
+  runbookId,
+  releaseId: release.releaseId,
+  drillTimestamp: new Date().toISOString(),
+  triggerInjected: specification.triggerKinds[0],
+  triggerAsserted: drill.triggerAsserted,
+  containmentAsserted: drill.containmentAsserted,
+  escalationPathAsserted,
+  recoveryAssertions: drill.recoveryAssertions,
+  negativeFixtureFailedAsExpected: drill.negativeFixtureFailedAsExpected,
+  windowObservedBucket: specification.window,
+  providerVerificationRequired: drill.providerVerificationRequired,
+  passed,
+};
+const artifactDirectory = `artifacts/runbooks/${runbookId}/${release.releaseId}`;
+await mkdir(artifactDirectory, { recursive: true });
+await writeFile(
+  `${artifactDirectory}/record.json`,
+  `${JSON.stringify(record, null, 2)}\n`,
+);
+if (!passed) {
+  process.stderr.write(`${runbookId} drill failed.\n`);
+  process.exit(1);
+}
+process.stdout.write(
+  `${runbookId} drill: PASS (${specification.gateId}; provider verification ${
+    drill.providerVerificationRequired ? "still required" : "not required"
+  })\n`,
+);

scripts/generate-build-manifest.mjs

@@ -1,17 +1,55 @@
+import { createHash } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import process from "node:process";
+import { z } from "zod";
+
+import {
+  ROUTE_REGISTRY,
+  ROUTE_RUNTIME_CONTRACT,
+} from "../src/features/installed-feature-contracts.js";
+import { runtimeConfigSchema } from "../src/bootstrap/runtime-config-schema.js";
 
 const packageJson = JSON.parse(await readFile("package.json", "utf8"));
 const packageManagerVersion = packageJson.packageManager.split("@").at(-1);
 const buildId = process.env.VITE_BUILD_ID ?? "local-build";
 const commitSha = process.env.VITE_COMMIT_SHA ?? "local";
+const releaseId = process.env.RELEASE_ID ?? "local-release";
 const runnerImage = process.env.CI_RUNNER_IMAGE ?? `${process.platform}-${process.arch}`;
+const builtAt = new Date().toISOString();
+const viteManifest = await readFile("dist/.vite/manifest.json", "utf8");
+const viteManifestObject =
+  /** @type {Record<string, {file: string, name?: string, isDynamicEntry?: boolean}>} */ (
+    JSON.parse(viteManifest)
+  );
+const assetManifestHash = createHash("sha256")
+  .update(viteManifest)
+  .digest("hex");
+const runtimeConfig = JSON.parse(await readFile("dist/config.json", "utf8"));
+/** @type {Record<string, string>} */
+const routeChunks = {};
+for (const definition of Object.values(ROUTE_REGISTRY)) {
+  const runtime =
+    /** @type {Record<string, {moduleId: string}>} */ (
+      ROUTE_RUNTIME_CONTRACT
+    )[definition.routeId];
+  const asset = Object.values(viteManifestObject).find(
+    (entry) => entry.name === runtime?.moduleId && entry.isDynamicEntry,
+  );
+  if (!runtime || !asset?.file) {
+    throw new Error(`Missing built route chunk: ${definition.routeId}`);
+  }
+  routeChunks[definition.chunkId] = asset.file;
+}
+const runtimeConfigJsonSchema = z.toJSONSchema(runtimeConfigSchema);
+
+runtimeConfig.BUILD_ID = buildId;
+runtimeConfig.RELEASE_ID = releaseId;
 
 const manifest = {
   schemaVersion: 1,
   buildId,
   commitSha,
-  generatedAt: new Date().toISOString(),
+  generatedAt: builtAt,
   buildContext: {
     nodeVersion: process.version,
     packageManagerVersion,
@@ -20,10 +58,38 @@ const manifest = {
   outputs: {
     directory: "dist",
     viteManifest: "dist/.vite/manifest.json",
+    routeChunks,
+    runtimeConfigSchema: "dist/runtime-config.schema.json",
   },
 };
 
+const releaseManifest = {
+  schemaVersion: 1,
+  appVersion: packageJson.version,
+  buildId,
+  commitSha,
+  configSchemaVersion: runtimeConfig.CONFIG_SCHEMA_VERSION,
+  apiContractVersion: runtimeConfig.API_CONTRACT_VERSION,
+  assetManifestHash,
+  releaseId,
+  builtAt,
+  routeChunks,
+};
+
 await mkdir("artifacts/release", { recursive: true });
+await writeFile("dist/config.json", `${JSON.stringify(runtimeConfig, null, 2)}\n`);
+await writeFile(
+  "dist/release-manifest.json",
+  `${JSON.stringify(releaseManifest, null, 2)}\n`,
+);
+await writeFile(
+  "dist/runtime-config.schema.json",
+  `${JSON.stringify(runtimeConfigJsonSchema, null, 2)}\n`,
+);
+await writeFile(
+  "artifacts/release/runtime-config.schema.json",
+  `${JSON.stringify(runtimeConfigJsonSchema, null, 2)}\n`,
+);
 await writeFile(
   "artifacts/release/build-manifest.json",
   `${JSON.stringify(manifest, null, 2)}\n`,

scripts/generate-supply-chain.mjs

@@ -0,0 +1,102 @@
+import { createHash } from "node:crypto";
+import { gzipSync } from "node:zlib";
+import {
+  mkdir,
+  readFile,
+  readdir,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import path from "node:path";
+
+/** @param {string} directory @returns {Promise<string[]>} */
+async function filesWithin(directory) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const nested = /** @type {string[][]} */ (await Promise.all(
+    entries.map((entry) => {
+      const target = path.join(directory, entry.name);
+      return entry.isDirectory() ? filesWithin(target) : [target];
+    }),
+  ));
+  return nested.flat().sort();
+}
+
+const packageJson = JSON.parse(await readFile("package.json", "utf8"));
+const lockfile = await readFile("pnpm-lock.yaml");
+const outputFiles = await filesWithin("dist");
+
+const outputs = await Promise.all(
+  outputFiles.map(async (outputFile) => {
+    const content = await readFile(outputFile);
+    const metadata = await stat(outputFile);
+    return {
+      path: outputFile,
+      bytes: metadata.size,
+      gzipBytes: gzipSync(content).byteLength,
+      sha256: createHash("sha256").update(content).digest("hex"),
+    };
+  }),
+);
+
+const dependencies = {
+  ...packageJson.dependencies,
+  ...packageJson.devDependencies,
+};
+const inventory = Object.entries(dependencies)
+  .sort(([left], [right]) => left.localeCompare(right))
+  .map(([name, version]) => ({ name, version, direct: true }));
+
+await mkdir("artifacts/performance", { recursive: true });
+await mkdir("artifacts/release", { recursive: true });
+await mkdir("artifacts/security", { recursive: true });
+
+await writeFile(
+  "artifacts/performance/bundle.json",
+  `${JSON.stringify(
+    {
+      schemaVersion: 1,
+      generatedAt: new Date().toISOString(),
+      context: {
+        nodeVersion: process.version,
+        packageManager: packageJson.packageManager,
+        runnerImage: process.env.CI_RUNNER_IMAGE ?? `${process.platform}-${process.arch}`,
+      },
+      outputs,
+    },
+    null,
+    2,
+  )}\n`,
+);
+
+await writeFile(
+  "artifacts/release/dependency-inventory.json",
+  `${JSON.stringify(
+    {
+      schemaVersion: 1,
+      lockfileSha256: createHash("sha256").update(lockfile).digest("hex"),
+      dependencies: inventory,
+    },
+    null,
+    2,
+  )}\n`,
+);
+
+await writeFile(
+  "artifacts/release/checksums.txt",
+  `${outputs.map((output) => `${output.sha256}  ${output.path}`).join("\n")}\n`,
+);
+
+await writeFile(
+  "artifacts/security/dependency-diff.json",
+  `${JSON.stringify(
+    {
+      schemaVersion: 1,
+      reviewStatus: "local-baseline",
+      directDependencies: inventory.length,
+      highRiskUnreviewed: [],
+      lockfileSha256: createHash("sha256").update(lockfile).digest("hex"),
+    },
+    null,
+    2,
+  )}\n`,
+);

scripts/lib/classify-vite-bundle.mjs

@@ -0,0 +1,49 @@
+/**
+ * @typedef {{
+ *   file: string,
+ *   isEntry?: boolean,
+ *   imports?: string[]
+ * }} ViteManifestEntry
+ */
+
+/**
+ * Static imports of an entry are part of initial JavaScript. Every remaining
+ * JavaScript output is governed by the lazy-chunk budget.
+ *
+ * @param {Record<string, ViteManifestEntry>} manifest
+ */
+export function classifyViteJavascript(manifest) {
+  const initialFiles = new Set();
+  const visitedKeys = new Set();
+  const pendingKeys = Object.entries(manifest)
+    .filter(([, entry]) => entry.isEntry)
+    .map(([key]) => key);
+  const missingImports = [];
+
+  while (pendingKeys.length > 0) {
+    const key = /** @type {string} */ (pendingKeys.pop());
+    if (visitedKeys.has(key)) continue;
+    visitedKeys.add(key);
+    const entry = manifest[key];
+    if (!entry) {
+      missingImports.push(key);
+      continue;
+    }
+    if (entry.file.endsWith(".js")) initialFiles.add(entry.file);
+    pendingKeys.push(...(entry.imports ?? []));
+  }
+
+  const allJavaScript = new Set(
+    Object.values(manifest)
+      .map((entry) => entry.file)
+      .filter((file) => file.endsWith(".js")),
+  );
+  const lazyFiles = [...allJavaScript].filter(
+    (file) => !initialFiles.has(file),
+  );
+  return Object.freeze({
+    initialFiles: Object.freeze([...initialFiles].sort()),
+    lazyFiles: Object.freeze(lazyFiles.sort()),
+    missingImports: Object.freeze(missingImports.sort()),
+  });
+}

scripts/lib/field-vitals-evidence.mjs

@@ -0,0 +1,122 @@
+import { z } from "zod";
+
+const WINDOW_MILLISECONDS = 28 * 24 * 60 * 60 * 1000;
+const nonEmptyString = z.string().trim().min(1);
+const timestamp = nonEmptyString.refine(
+  (value) => Number.isFinite(Date.parse(value)),
+  "must be an RFC 3339 timestamp",
+);
+const sampleSchema = z
+  .object({
+    timestamp,
+    consent: z.boolean(),
+    releaseId: nonEmptyString,
+    routeId: nonEmptyString.regex(/^[A-Z][A-Z0-9_]*$/),
+    lcpMs: z.number().finite().nonnegative(),
+    cls: z.number().finite().nonnegative(),
+    inpMs: z.number().finite().nonnegative(),
+  })
+  .strict();
+
+const fieldEvidenceInputSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    environment: z.literal("production"),
+    releaseId: nonEmptyString.refine(
+      (value) => value !== "local-release",
+      "must identify an immutable production release",
+    ),
+    source: z
+      .object({
+        system: nonEmptyString,
+        exportId: nonEmptyString,
+      })
+      .strict(),
+    privacy: z
+      .object({
+        approved: z.literal(true),
+        approvalRef: nonEmptyString,
+      })
+      .strict(),
+    window: z
+      .object({
+        start: timestamp,
+        end: timestamp,
+      })
+      .strict(),
+    thresholdDecision: z
+      .object({
+        status: z.literal("approved"),
+        minimumEligibleSamples: z.number().int().positive(),
+        owner: nonEmptyString,
+        reviewedAt: timestamp,
+        evidenceRef: nonEmptyString,
+      })
+      .strict(),
+    samples: z.array(sampleSchema),
+  })
+  .strict()
+  .superRefine((input, context) => {
+    const start = Date.parse(input.window.start);
+    const end = Date.parse(input.window.end);
+    if (end - start !== WINDOW_MILLISECONDS) {
+      context.addIssue({
+        code: "custom",
+        path: ["window"],
+        message: "must cover exactly 28 days",
+      });
+    }
+  });
+
+/**
+ * @param {unknown} input
+ * @param {string | undefined} configuredMinimum
+ * @param {Date} [now]
+ */
+export function validateFieldEvidenceInput(
+  input,
+  configuredMinimum,
+  now = new Date(),
+) {
+  const parsed = fieldEvidenceInputSchema.safeParse(input);
+  const failures = parsed.success
+    ? []
+    : parsed.error.issues.map(
+        (issue) => `${issue.path.join(".") || "input"}: ${issue.message}`,
+      );
+  const minimumEligibleSamples = Number(configuredMinimum);
+  if (
+    configuredMinimum === undefined ||
+    !Number.isInteger(minimumEligibleSamples) ||
+    minimumEligibleSamples <= 0
+  ) {
+    failures.push("MIN_ELIGIBLE_SAMPLES: must be a positive integer");
+  }
+
+  if (parsed.success) {
+    if (
+      parsed.data.thresholdDecision.minimumEligibleSamples !==
+      minimumEligibleSamples
+    ) {
+      failures.push(
+        "MIN_ELIGIBLE_SAMPLES: does not match the approved threshold decision",
+      );
+    }
+    if (Date.parse(parsed.data.window.end) > now.getTime()) {
+      failures.push("window.end: must not be in the future");
+    }
+    if (Date.parse(parsed.data.thresholdDecision.reviewedAt) > now.getTime()) {
+      failures.push("thresholdDecision.reviewedAt: must not be in the future");
+    }
+  }
+
+  return Object.freeze({
+    data: parsed.success ? parsed.data : null,
+    failures: Object.freeze(failures),
+    minimumEligibleSamples:
+      Number.isInteger(minimumEligibleSamples) && minimumEligibleSamples > 0
+        ? minimumEligibleSamples
+        : null,
+    passed: parsed.success && failures.length === 0,
+  });
+}

scripts/lib/hosting-probe.mjs

@@ -0,0 +1,68 @@
+const LOOPBACK_IPV4 = /^127(?:\.\d{1,3}){3}$/;
+
+/**
+ * A release gate must not promote a local preview server as live hosting
+ * evidence.
+ *
+ * @param {string} value
+ * @returns {
+ *   | { passed: true; reason: null; url: URL; observedOrigin: string }
+ *   | { passed: false; reason: string; url: URL | null; observedOrigin: string | null }
+ * }
+ */
+export function classifyLiveHostingBaseUrl(value) {
+  /** @type {URL} */
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return {
+      passed: false,
+      reason: "HOSTING_BASE_URL must be an absolute URL",
+      url: null,
+      observedOrigin: null,
+    };
+  }
+
+  const observedOrigin = url.origin;
+  const hostname = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  if (url.protocol !== "https:") {
+    return {
+      passed: false,
+      reason: "live hosting evidence requires HTTPS",
+      url,
+      observedOrigin,
+    };
+  }
+  if (url.username || url.password) {
+    return {
+      passed: false,
+      reason: "HOSTING_BASE_URL must not contain credentials",
+      url,
+      observedOrigin,
+    };
+  }
+  if (
+    hostname === "localhost" ||
+    hostname.endsWith(".localhost") ||
+    hostname === "::1" ||
+    hostname === "0.0.0.0" ||
+    LOOPBACK_IPV4.test(hostname)
+  ) {
+    return {
+      passed: false,
+      reason: "local or loopback hosts are not live deployment evidence",
+      url,
+      observedOrigin,
+    };
+  }
+  if (url.pathname !== "/" || url.search || url.hash) {
+    return {
+      passed: false,
+      reason: "HOSTING_BASE_URL must be the canonical root URL",
+      url,
+      observedOrigin,
+    };
+  }
+  return { passed: true, reason: null, url, observedOrigin };
+}

scripts/lib/manual-a11y-evidence.mjs

@@ -0,0 +1,58 @@
+import { ROUTE_REGISTRY } from "../../src/features/installed-feature-contracts.js";
+
+export const MANUAL_A11Y_ROUTE_IDS = Object.freeze(
+  Object.values(ROUTE_REGISTRY).map((route) => route.routeId),
+);
+
+const REVIEW_FIELDS = Object.freeze([
+  "M1 Keyboard",
+  "M2 Visible focus",
+  "M3 Route focus",
+  "M4 Modal focus",
+  "M5 Error association",
+  "M6 Color signal",
+  "M7 Reduced motion",
+  "Screen reader",
+]);
+
+/** @param {string} content */
+export function validateManualA11yEvidence(content) {
+  const fields = Object.fromEntries(
+    content
+      .split(/\r?\n/)
+      .map((line) => /^([^:]+):\s*(.*)$/.exec(line))
+      .filter(Boolean)
+      .map((match) => [
+        /** @type {RegExpExecArray} */ (match)[1].trim(),
+        /** @type {RegExpExecArray} */ (match)[2].trim(),
+      ]),
+  );
+  const failures = [];
+  if (fields.Status !== "reviewed") failures.push("Status");
+  if (!fields["Route ID"]) failures.push("Route ID");
+  if (!fields["Release ID"]) failures.push("Release ID");
+  if (!fields.Reviewer) failures.push("Reviewer");
+  if (!fields.Signature) failures.push("Signature");
+  if (fields.Attestation !== "accepted") failures.push("Attestation");
+  if (
+    !fields["Reviewed at"] ||
+    !Number.isFinite(Date.parse(fields["Reviewed at"]))
+  ) {
+    failures.push("Reviewed at");
+  }
+
+  for (const field of REVIEW_FIELDS) {
+    const result = fields[field];
+    if (
+      result !== "pass" &&
+      !/^not-applicable \(.+\)$/.test(result ?? "")
+    ) {
+      failures.push(field);
+    }
+  }
+  return Object.freeze({
+    fields: Object.freeze(fields),
+    failures: Object.freeze(failures),
+    passed: failures.length === 0,
+  });
+}

scripts/run-ci-gate.mjs

@@ -0,0 +1,86 @@
+import { spawnSync } from "node:child_process";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const gateId = process.argv
+  .slice(2)
+  .find((argument) => /^FE-GATE-\d{3}$/.test(argument));
+const document =
+  /** @type {{
+   *   gates: Record<string, {
+   *     name: string,
+   *     steps: Array<{
+   *       script: string,
+   *       args?: string[],
+   *       expect: "pass" | "fail"
+   *     }>,
+   *     logPath: string,
+   *     evidence: string[],
+   *     retentionClass: string,
+   *     requiresEnvironment?: string[]
+   *   }>
+   * }} */ (JSON.parse(await readFile("config/ci/gates.json", "utf8")));
+const gate = gateId ? document.gates[gateId] : undefined;
+if (!gateId || !gate) {
+  process.stderr.write("Usage: ci:gate -- FE-GATE-001..FE-GATE-026\n");
+  process.exit(2);
+}
+
+const output = [];
+let passed = true;
+for (const variable of gate.requiresEnvironment ?? []) {
+  if (!process.env[variable]) {
+    output.push(`missing required environment: ${variable}`);
+    passed = false;
+  }
+}
+
+if (passed) {
+  for (const step of gate.steps) {
+    const result = spawnSync(
+      "corepack",
+      ["pnpm", step.script, ...(step.args ?? [])],
+      { encoding: "utf8", env: process.env },
+    );
+    output.push(
+      `$ corepack pnpm ${step.script} ${(step.args ?? []).join(" ")}`.trim(),
+      result.stdout,
+      result.stderr,
+    );
+    const exitedSuccessfully = result.status === 0;
+    const expectationMet =
+      step.expect === "pass" ? exitedSuccessfully : !exitedSuccessfully;
+    if (!expectationMet) {
+      output.push(
+        `expectation failed: expected ${step.expect}, exit=${result.status}`,
+      );
+      passed = false;
+      break;
+    }
+  }
+}
+
+await mkdir(path.dirname(gate.logPath), { recursive: true });
+await writeFile(gate.logPath, `${output.filter(Boolean).join("\n")}\n`);
+
+if (passed) {
+  for (const evidencePath of gate.evidence) {
+    try {
+      await access(evidencePath);
+    } catch {
+      output.push(`missing evidence: ${evidencePath}`);
+      passed = false;
+    }
+  }
+  if (!passed) {
+    await writeFile(gate.logPath, `${output.filter(Boolean).join("\n")}\n`);
+  }
+}
+
+if (!passed) {
+  process.stderr.write(`${gateId} ${gate.name}: FAIL\n`);
+  process.exit(1);
+}
+process.stdout.write(
+  `${gateId} ${gate.name}: PASS (${gate.retentionClass})\n`,
+);

scripts/security-scan.mjs

@@ -0,0 +1,82 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const scanRoots = ["src", "dist"];
+const findings = /** @type {Array<{ruleId: string, file: string}>} */ ([]);
+const patterns = [
+  { id: "private-key", expression: /-----BEGIN (?:RSA |EC )?PRIVATE KEY-----/g },
+  { id: "aws-access-key", expression: /\bAKIA[0-9A-Z]{16}\b/g },
+  { id: "github-token", expression: /\bgh[pousr]_[A-Za-z0-9_]{30,}\b/g },
+  {
+    id: "assigned-secret",
+    expression:
+      /\b(?:client_secret|password|private_key)\s*[:=]\s*["'][^"'${}]{12,}["']/gi,
+  },
+];
+
+/** @param {string} directory @returns {Promise<string[]>} */
+async function filesWithin(directory) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const nested = /** @type {string[][]} */ (await Promise.all(
+    entries.map((entry) => {
+      const target = path.join(directory, entry.name);
+      return entry.isDirectory() ? filesWithin(target) : [target];
+    }),
+  ));
+  return nested.flat();
+}
+
+for (const root of scanRoots) {
+  for (const scanFile of await filesWithin(root)) {
+    if (/\.(png|jpg|jpeg|gif|woff2?|zip)$/i.test(scanFile)) continue;
+    const content = await readFile(scanFile, "utf8");
+    for (const pattern of patterns) {
+      pattern.expression.lastIndex = 0;
+      if (pattern.expression.test(content)) {
+        findings.push({ ruleId: pattern.id, file: scanFile });
+      }
+    }
+  }
+}
+
+const sarif = {
+  version: "2.1.0",
+  $schema:
+    "https://json.schemastore.org/sarif-2.1.0.json",
+  runs: [
+    {
+      tool: {
+        driver: {
+          name: "ca-frontend-secret-scan",
+          rules: patterns.map((pattern) => ({
+            id: pattern.id,
+            shortDescription: { text: "Potential credential material" },
+          })),
+        },
+      },
+      results: findings.map((finding) => ({
+        ruleId: finding.ruleId,
+        message: { text: "Potential secret material must be removed." },
+        locations: [
+          {
+            physicalLocation: {
+              artifactLocation: { uri: finding.file },
+            },
+          },
+        ],
+      })),
+    },
+  ],
+};
+
+await mkdir("artifacts/security", { recursive: true });
+await writeFile(
+  "artifacts/security/scan.sarif",
+  `${JSON.stringify(sarif, null, 2)}\n`,
+);
+
+if (findings.length > 0) {
+  process.stderr.write(`Security scan found ${findings.length} blocking result(s).\n`);
+  process.exit(1);
+}
+process.stdout.write("Source and built-asset secret scan: PASS\n");

scripts/test-performance.mjs

@@ -0,0 +1,155 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { performance } from "node:perf_hooks";
+import process from "node:process";
+
+import { chromium } from "@playwright/test";
+
+import { evaluateLabBudget } from "../src/application/policies/performance-budgets.js";
+import { ROUTE_REGISTRY } from "../src/features/installed-feature-contracts.js";
+
+const server = spawn(
+  "corepack",
+  ["pnpm", "preview", "--host", "127.0.0.1", "--port", "4173"],
+  { stdio: "ignore" },
+);
+const baseUrl = "http://127.0.0.1:4173";
+
+async function waitForServer() {
+  for (let attempt = 0; attempt < 50; attempt += 1) {
+    try {
+      const response = await fetch(baseUrl);
+      if (response.ok) return;
+    } catch {
+      // The bounded retry loop handles startup races.
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  throw new Error("Preview server did not become ready.");
+}
+
+try {
+  await waitForServer();
+  const release = JSON.parse(
+    await readFile("dist/release-manifest.json", "utf8"),
+  );
+  const thresholds = JSON.parse(
+    await readFile("config/performance/budgets.json", "utf8"),
+  ).lab;
+  const browser = await chromium.launch();
+  try {
+    const context = await browser.newContext({
+      viewport: { width: 1280, height: 720 },
+    });
+    const page = await context.newPage();
+    const cdp = await context.newCDPSession(page);
+    await cdp.send("Network.enable");
+    await cdp.send("Network.emulateNetworkConditions", {
+      offline: false,
+      latency: 40,
+      downloadThroughput: 200_000,
+      uploadThroughput: 93_750,
+      connectionType: "cellular4g",
+    });
+    await cdp.send("Emulation.setCPUThrottlingRate", { rate: 4 });
+    await page.addInitScript(() => {
+      const evidence = { lcpMs: 0, cls: 0 };
+      /** @type {any} */ (window).__contractPerformance = evidence;
+      new PerformanceObserver((list) => {
+        for (const entry of list.getEntries()) evidence.lcpMs = entry.startTime;
+      }).observe({ type: "largest-contentful-paint", buffered: true });
+      new PerformanceObserver((list) => {
+        for (const entry of list.getEntries()) {
+          if (!(/** @type {any} */ (entry)).hadRecentInput) {
+            evidence.cls += /** @type {any} */ (entry).value;
+          }
+        }
+      }).observe({ type: "layout-shift", buffered: true });
+    });
+    await page.goto(baseUrl, { waitUntil: "networkidle" });
+    const targetLabel = Object.values(ROUTE_REGISTRY).find(
+      (definition) => definition.access === "integration-defined",
+    )?.navigationLabel;
+    if (!targetLabel) {
+      throw new Error("Performance route must be present in navigation.");
+    }
+    const interactionStarted = performance.now();
+    await page.getByRole("link", { name: targetLabel }).click();
+    await page.getByRole("heading", { name: "세션이 필요합니다." }).waitFor();
+    const namedInteractionMs = performance.now() - interactionStarted;
+    const paint = await page.evaluate(
+      () => /** @type {any} */ (window).__contractPerformance,
+    );
+    const contextMetadata = {
+      runner: {
+        platform: process.platform,
+        architecture: process.arch,
+        nodeVersion: process.version,
+      },
+      browser: { name: "chromium", version: await browser.version() },
+      viewport: { width: 1280, height: 720 },
+      network: {
+        profile: "contract-fast-4g",
+        latencyMs: 40,
+        downloadBytesPerSecond: 200_000,
+        uploadBytesPerSecond: 93_750,
+      },
+      cpu: { throttlingRate: 4 },
+      cache: { state: "cold", isolation: "new-browser-context" },
+      build: { buildId: release.buildId, releaseId: release.releaseId },
+    };
+    const metrics = {
+      lcpMs: Math.round(paint.lcpMs),
+      cls: Number(paint.cls.toFixed(4)),
+      namedInteractionMs: Math.round(namedInteractionMs),
+    };
+    const result = evaluateLabBudget(
+      { context: contextMetadata, metrics },
+      thresholds,
+    );
+    const fixtures = [
+      {
+        name: "missing-context",
+        passed: !evaluateLabBudget({ metrics }, thresholds).passed,
+      },
+      {
+        name: "lcp-over-threshold",
+        passed: !evaluateLabBudget(
+          {
+            context: contextMetadata,
+            metrics: { ...metrics, lcpMs: thresholds.lcpMs + 1 },
+          },
+          thresholds,
+        ).passed,
+      },
+    ];
+    const passed = result.passed && fixtures.every((fixture) => fixture.passed);
+    await mkdir("artifacts/performance", { recursive: true });
+    await writeFile(
+      "artifacts/performance/lab.json",
+      `${JSON.stringify(
+        {
+          schemaVersion: 1,
+          generatedAt: new Date().toISOString(),
+          context: contextMetadata,
+          metrics,
+          thresholds,
+          fixtures,
+          passed,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    if (!passed) {
+      throw new Error(`Lab performance failed: ${JSON.stringify(metrics)}`);
+    }
+    process.stdout.write(
+      `Lab performance: PASS (LCP ${metrics.lcpMs}ms, CLS ${metrics.cls}, interaction ${metrics.namedInteractionMs}ms)\n`,
+    );
+  } finally {
+    await browser.close();
+  }
+} finally {
+  server.kill("SIGTERM");
+}

scripts/test-sample-removal.mjs

@@ -0,0 +1,231 @@
+import { spawnSync } from "node:child_process";
+import {
+  cp,
+  mkdir,
+  readFile,
+  readdir,
+  rm,
+  symlink,
+  writeFile,
+} from "node:fs/promises";
+import path from "node:path";
+
+const fixtureRoot = path.resolve(".tmp/reference-feature-removal");
+const pnpmCli = /** @type {string} */ (process.env.npm_execpath);
+const featureSource = "src/features/reference-feature";
+const featureTests = "tests/features/reference-feature";
+const featureOwnedPaths = [
+  featureSource,
+  featureTests,
+  "tests/e2e/reference-form.spec.js",
+];
+const copyTargets = [
+  "src",
+  "tests",
+  "scripts",
+  "config",
+  "public",
+  "index.html",
+  "package.json",
+  "tsconfig.base.json",
+  "tsconfig.json",
+  "tsconfig.app.json",
+  "tsconfig.node.json",
+  "tsconfig.test.json",
+  "vite.config.js",
+  "vitest.config.js",
+  "playwright.config.js",
+  "eslint.config.js",
+  ".dependency-cruiser.cjs",
+];
+
+const emptyContracts = `import { PLATFORM_ROUTE_RUNTIME_CONTRACT } from "../contracts/route-runtime-contract.js";
+import { PLATFORM_ROUTE_REGISTRY } from "../contracts/routes.js";
+
+export const INSTALLED_FEATURE_CONTRACTS =
+  /** @type {readonly unknown[]} */ (Object.freeze([]));
+export const ROUTE_REGISTRY = PLATFORM_ROUTE_REGISTRY;
+export const ROUTE_RUNTIME_CONTRACT = PLATFORM_ROUTE_RUNTIME_CONTRACT;
+export const API_OPERATIONS = Object.freeze({});
+export const QUERY_REGISTRY = Object.freeze({});
+export const NAVIGATION_ROUTES = Object.freeze(
+  Object.values(ROUTE_REGISTRY)
+    .filter((definition) => definition.navigationOrder !== null)
+    .sort(
+      (left, right) =>
+        /** @type {number} */ (left.navigationOrder) -
+        /** @type {number} */ (right.navigationOrder),
+    ),
+);
+/** @param {string} routeId */
+export function getRoute(routeId) {
+  const registry =
+    /** @type {Readonly<Record<string, import("../contracts/routes.js").RouteDefinition>>} */ (
+      ROUTE_REGISTRY
+    );
+  const selected = registry[routeId];
+  if (!selected) throw new Error(\`Unregistered route: \${routeId}\`);
+  return selected;
+}
+/** @param {string} routeId */
+export function routePath(routeId) {
+  return getRoute(routeId).path;
+}
+`;
+
+const emptyRuntimes = `import { PLATFORM_ROUTE_CODECS } from "../presentation/routes/platform-route-codecs.js";
+import { PLATFORM_ROUTE_RUNTIME } from "../presentation/routes/route-runtime.js";
+
+export const ROUTE_CODECS = PLATFORM_ROUTE_CODECS;
+export const ROUTE_RUNTIME = PLATFORM_ROUTE_RUNTIME;
+`;
+
+const emptyAdapters = `type FeatureContext = Readonly<{
+  createHttpClient(contract: Readonly<Record<string, unknown>>): unknown;
+}>;
+export function createInstalledFeatureInputs(_context: FeatureContext) {
+  void _context;
+  return Object.freeze({});
+}
+`;
+
+const emptyMessages = `export const INSTALLED_MESSAGE_CATALOGS = Object.freeze({
+  "ko-KR": Object.freeze({}),
+  "en-US": Object.freeze({}),
+});
+`;
+
+/** @param {string} directory @returns {Promise<string[]>} */
+async function filesBelow(directory) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const groups = await Promise.all(
+    entries.map((entry) => {
+      const target = path.join(directory, entry.name);
+      return entry.isDirectory() ? filesBelow(target) : [target];
+    }),
+  );
+  return groups.flat();
+}
+
+/** @param {string} script @param {string[]} [extra] */
+function runPnpm(script, extra = []) {
+  const result = spawnSync(process.execPath, [pnpmCli, script, ...extra], {
+    cwd: fixtureRoot,
+    stdio: "inherit",
+  });
+  return result.status === 0;
+}
+
+await rm(fixtureRoot, { recursive: true, force: true });
+await mkdir(fixtureRoot, { recursive: true });
+for (const target of copyTargets) {
+  await cp(target, path.join(fixtureRoot, target), { recursive: true });
+}
+await symlink(path.resolve("node_modules"), path.join(fixtureRoot, "node_modules"), "dir");
+
+for (const ownedPath of featureOwnedPaths) {
+  await rm(path.join(fixtureRoot, ownedPath), {
+    recursive: true,
+    force: true,
+  });
+}
+await writeFile(
+  path.join(fixtureRoot, "src/features/installed-feature-contracts.js"),
+  emptyContracts,
+);
+await writeFile(
+  path.join(fixtureRoot, "src/features/installed-feature-runtimes.tsx"),
+  emptyRuntimes,
+);
+await writeFile(
+  path.join(fixtureRoot, "src/features/installed-feature-adapters.ts"),
+  emptyAdapters,
+);
+await writeFile(
+  path.join(fixtureRoot, "src/features/installed-feature-messages.js"),
+  emptyMessages,
+);
+
+/** @type {string[]} */
+const residue = [];
+for (const root of ["src", "tests"]) {
+  for (const file of await filesBelow(path.join(fixtureRoot, root))) {
+    const relative = path.relative(fixtureRoot, file);
+    const content = await readFile(file, "utf8");
+    if (
+      /REFERENCE_RESOURCE|reference-feature|reference-resource/i.test(
+        `${relative}\n${content}`,
+      )
+    ) {
+      residue.push(relative);
+    }
+  }
+}
+
+const checks = [
+  ["typecheck", runPnpm("check:types")],
+  ["architecture", runPnpm("check:architecture")],
+  ["registry", runPnpm("check:registries")],
+  ["unit-integration", runPnpm("test:all")],
+  [
+    "home-smoke",
+    runPnpm("exec", [
+      "vitest",
+      "run",
+      "tests/component/router.test.jsx",
+      "--reporter=default",
+    ]),
+  ],
+  ["build", runPnpm("build")],
+];
+/** @type {string[]} */
+const builtResidue = [];
+for (const file of await filesBelow(path.join(fixtureRoot, "dist"))) {
+  if (!/\.(?:js|css|html|json)$/.test(file)) continue;
+  const content = await readFile(file, "utf8");
+  if (
+    /REFERENCE_RESOURCE|reference-feature|reference-resource/i.test(content)
+  ) {
+    builtResidue.push(path.relative(fixtureRoot, file));
+  }
+}
+const routeCatalog = await import(
+  `${new URL(
+    "../src/features/installed-feature-contracts.js",
+    `file://${fixtureRoot}/scripts/`,
+  ).href}?removed=${Date.now()}`
+);
+const routeIds = Object.keys(routeCatalog.ROUTE_REGISTRY);
+const routeAbsent = routeIds.every((routeId) => !routeId.startsWith("REFERENCE_"));
+checks.push(["route-absent", routeAbsent]);
+checks.push(["fixture-id-residue", residue.length === 0]);
+checks.push(["built-fixture-id-residue", builtResidue.length === 0]);
+
+const passed = checks.every(([, result]) => result);
+await mkdir("artifacts/tests", { recursive: true });
+await writeFile(
+  "artifacts/tests/sample-removal.xml",
+  `<?xml version="1.0" encoding="UTF-8"?>\n` +
+    `<testsuite name="reference-feature-removal" tests="${checks.length}" failures="${passed ? 0 : 1}">` +
+    checks
+      .map(
+        ([name, result]) =>
+          `<testcase name="${name}">${result ? "" : `<failure>${[...residue, ...builtResidue].join(", ")}</failure>`}</testcase>`,
+      )
+      .join("") +
+    `</testsuite>\n`,
+);
+await rm(fixtureRoot, { recursive: true, force: true });
+
+if (!passed) {
+  const failures = checks
+    .filter(([, result]) => !result)
+    .map(([name]) => name);
+  process.stderr.write(
+    `Reference feature removal failed: ${failures.join(", ")}; residue: ${[...residue, ...builtResidue].join(", ")}\n`,
+  );
+  process.exit(1);
+}
+process.stdout.write(
+  `Reference feature removal: PASS (${checks.length} checks, no fixture IDs)\n`,
+);

scripts/verify-a11y-manual.mjs

@@ -0,0 +1,71 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+
+import {
+  MANUAL_A11Y_ROUTE_IDS,
+  validateManualA11yEvidence,
+} from "./lib/manual-a11y-evidence.mjs";
+
+/** @type {Array<{
+ * routeId: string;
+ * path: string;
+ * reviewer: string | null;
+ * reviewedAt: string | null;
+ * releaseId: string | null;
+ * failures: readonly string[];
+ * passed: boolean;
+ * }>} */
+const results = [];
+for (const routeId of MANUAL_A11Y_ROUTE_IDS) {
+  const path = `artifacts/tests/a11y-manual/${routeId}.md`;
+  const evidence = await readFile(path, "utf8");
+  const validation = validateManualA11yEvidence(evidence);
+  const failures =
+    validation.fields["Route ID"] === routeId
+      ? validation.failures
+      : Object.freeze([...validation.failures, "Route ID mismatch"]);
+  results.push({
+    routeId,
+    path,
+    reviewer: validation.fields.Reviewer ?? null,
+    reviewedAt: validation.fields["Reviewed at"] ?? null,
+    releaseId: validation.fields["Release ID"] ?? null,
+    failures,
+    passed: validation.passed && failures.length === 0,
+  });
+}
+const releaseIds = new Set(results.map((result) => result.releaseId));
+const passed =
+  results.every((result) => result.passed) &&
+  releaseIds.size === 1 &&
+  results.every((result) => Boolean(result.releaseId));
+
+await mkdir("artifacts/tests/a11y-manual", { recursive: true });
+await writeFile(
+  "artifacts/tests/a11y-manual/report.json",
+  `${JSON.stringify(
+    {
+      schemaVersion: 1,
+      generatedAt: new Date().toISOString(),
+      scope: MANUAL_A11Y_ROUTE_IDS,
+      results,
+      coherentRelease: releaseIds.size === 1,
+      passed,
+    },
+    null,
+    2,
+  )}\n`,
+);
+
+if (!passed) {
+  const failures = results
+    .filter((result) => !result.passed)
+    .map((result) => `${result.routeId}: ${result.failures.join(", ")}`);
+  if (releaseIds.size !== 1) failures.push("release IDs do not match");
+  process.stderr.write(
+    `Manual accessibility evidence is incomplete:\n${failures.join("\n")}\n`,
+  );
+  process.exit(1);
+}
+process.stdout.write(
+  `Manual accessibility evidence: PASS (${results.length} routes)\n`,
+);

scripts/verify-documentation-readiness.mjs

@@ -0,0 +1,68 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+
+const ledger = JSON.parse(
+  await readFile("docs/architecture/review-ledger.json", "utf8"),
+);
+const evidence = await readFile(ledger.evidenceReport.repoPath, "utf8");
+const results = [];
+for (const [diagram, review] of Object.entries(ledger.reviews)) {
+  const sourceReferenced = evidence.includes(review.sourcePath);
+  const digestReferenced =
+    /^[0-9a-f]{64}$/.test(review.sha256) &&
+    evidence.includes(review.sha256);
+  const scorePass =
+    review.thresholdSatisfied === true &&
+    review.verdict === "PASS" &&
+    typeof review.score === "number" &&
+    evidence.includes(`| ${review.score} | PASS |`);
+  results.push({
+    diagram,
+    sourcePath: review.sourcePath,
+    sha256: review.sha256,
+    sourceReferenced,
+    digestReferenced,
+    reviewer: ledger.reviewer,
+    score: review.score,
+    scorePass,
+    passed:
+      sourceReferenced &&
+      digestReferenced &&
+      ledger.reviewer === "wiki-diagram-reviewer" &&
+      ledger.standard === "rules/diagram-standards.md v2" &&
+      scorePass &&
+      ledger.status === "PASS_SCOPED",
+  });
+}
+const reportDigestValid =
+  /^[0-9a-f]{64}$/.test(ledger.evidenceReport.canonicalSha256) &&
+  evidence.includes(ledger.evidenceReport.canonicalSha256);
+const passed =
+  reportDigestValid &&
+  results.length === 2 &&
+  results.every((result) => result.passed);
+await mkdir("artifacts/quality", { recursive: true });
+await writeFile(
+  "artifacts/quality/documentation-review.json",
+  `${JSON.stringify(
+    {
+      schemaVersion: 1,
+      generatedAt: new Date().toISOString(),
+      status: ledger.status,
+      reviewer: ledger.reviewer,
+      standard: ledger.standard,
+      evidenceReport: ledger.evidenceReport,
+      reportDigestValid,
+      results,
+      passed,
+    },
+    null,
+    2,
+  )}\n`,
+);
+if (!passed) {
+  process.stderr.write(
+    "Documentation readiness: FAIL_UNVERIFIED (canonical scoped-review evidence is incomplete)\n",
+  );
+  process.exit(1);
+}
+process.stdout.write("Documentation readiness: PASS_SCOPED\n");

scripts/verify-hosting-headers.mjs

@@ -0,0 +1,183 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+
+import { classifyLiveHostingBaseUrl } from "./lib/hosting-probe.mjs";
+
+const cachePolicy = JSON.parse(
+  await readFile("config/hosting/cache-policy.json", "utf8"),
+);
+const securityPolicy = JSON.parse(
+  await readFile("config/hosting/security-headers.json", "utf8"),
+);
+const baseUrl = process.env.HOSTING_BASE_URL;
+const liveTarget = baseUrl ? classifyLiveHostingBaseUrl(baseUrl) : null;
+const distFiles = (await readdir("dist", { recursive: true })).map(String);
+const publicSourceMaps = distFiles.filter((file) => file.endsWith(".map"));
+const publicServiceWorkers = distFiles.filter((file) =>
+  /(?:^|\/)(?:service-worker|sw)(?:[.-][^/]*)?\.js$/i.test(file),
+);
+
+/** @type {Record<string, Record<string, string>>} */
+let responses = {};
+let mode;
+/** @type {Array<{
+ * surface: string;
+ * header: string;
+ * expected: unknown;
+ * observed: unknown;
+ * reason?: string;
+ * passed: boolean;
+ * }>} */
+const probeResults = [];
+
+if (liveTarget?.passed) {
+  mode = "live";
+  const assets = await readdir("dist/assets");
+  const hashedJavaScript = assets.find((file) => file.endsWith(".js"));
+  if (!hashedJavaScript) throw new Error("No built hashed JavaScript found.");
+  const paths = {
+    index: "/",
+    runtimeConfig: "/config.json",
+    releaseManifest: "/release-manifest.json",
+    hashedAsset: `/assets/${hashedJavaScript}`,
+  };
+  responses = {};
+  for (const [surface, pathname] of Object.entries(paths)) {
+    const requestedUrl = new URL(pathname, liveTarget.url);
+    try {
+      const response = await fetch(requestedUrl, { redirect: "follow" });
+      const finalUrl = new URL(response.url);
+      probeResults.push(
+        {
+          surface,
+          header: "http-status",
+          expected: 200,
+          observed: response.status,
+          passed: response.status === 200,
+        },
+        {
+          surface,
+          header: "final-origin",
+          expected: liveTarget.url.origin,
+          observed: finalUrl.origin,
+          passed: finalUrl.origin === liveTarget.url.origin,
+        },
+      );
+      responses[surface] = Object.fromEntries(
+        [...response.headers.entries()].map(([name, value]) => [
+          name.toLowerCase(),
+          value,
+        ]),
+      );
+    } catch (error) {
+      probeResults.push({
+        surface,
+        header: "transport",
+        expected: "reachable",
+        observed: error instanceof Error ? error.name : "UnknownError",
+        passed: false,
+      });
+    }
+  }
+} else if (liveTarget) {
+  mode = "invalid-live";
+  probeResults.push({
+    surface: "deployment",
+    header: "base-url",
+    expected: "canonical non-loopback HTTPS root URL",
+    observed: liveTarget.observedOrigin,
+    reason: liveTarget.reason,
+    passed: false,
+  });
+} else {
+  mode = "fixture";
+  responses = JSON.parse(
+    await readFile("config/hosting/response-headers.fixture.json", "utf8"),
+  ).responses;
+}
+
+const results = [...probeResults];
+for (const [surface, policy] of Object.entries(cachePolicy.surfaces)) {
+  if (!("cacheControl" in policy)) continue;
+  const observed = responses[surface]?.["cache-control"];
+  results.push({
+    surface,
+    header: "cache-control",
+    expected: policy.cacheControl,
+    observed,
+    passed: observed === policy.cacheControl,
+  });
+  const observedContentType = responses[surface]?.["content-type"];
+  const observedMime = observedContentType
+    ?.split(";", 1)[0]
+    .trim()
+    .toLowerCase();
+  results.push({
+    surface,
+    header: "content-type",
+    expected: policy.contentTypes,
+    observed: observedContentType,
+    passed: policy.contentTypes.includes(observedMime),
+  });
+  if (policy.securityHeaders) {
+    for (const [header, expected] of Object.entries(securityPolicy.headers)) {
+      const observedSecurity = responses[surface]?.[header.toLowerCase()];
+      results.push({
+        surface,
+        header: header.toLowerCase(),
+        expected,
+        observed: observedSecurity,
+        passed: observedSecurity === expected,
+      });
+    }
+  }
+}
+
+results.push({
+  surface: "sourceMap",
+  header: "public",
+  expected: false,
+  observed: publicSourceMaps.length > 0,
+  passed:
+    cachePolicy.surfaces.sourceMap.public === false &&
+    publicSourceMaps.length === 0,
+});
+results.push({
+  surface: "serviceWorker",
+  header: "enabled",
+  expected: false,
+  observed: publicServiceWorkers.length > 0,
+  passed:
+    cachePolicy.surfaces.serviceWorker.enabled === false &&
+    publicServiceWorkers.length === 0,
+});
+
+const passed = results.every((result) => result.passed);
+await mkdir("artifacts/release", { recursive: true });
+await writeFile(
+  "artifacts/release/hosting-headers.json",
+  `${JSON.stringify(
+    {
+      schemaVersion: 1,
+      generatedAt: new Date().toISOString(),
+      mode,
+      baseUrl: liveTarget?.observedOrigin ?? null,
+      providerVerificationRequired: mode !== "live",
+      results,
+      passed,
+    },
+    null,
+    2,
+  )}\n`,
+);
+
+if (!passed) {
+  process.stderr.write(
+    "Hosting cache/content-type/security header verification failed.\n",
+  );
+  process.exit(1);
+}
+process.stdout.write(
+  `Hosting header contract: PASS (${mode}; live verification ${
+    mode === "live" ? "complete" : "required before promotion"
+  })\n`,
+);

scripts/verify-release.mjs

@@ -0,0 +1,164 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+
+import { verifyCompatibilityTuple } from "../src/application/policies/compatibility.js";
+import {
+  compareReleaseToRuntime,
+  RELEASE_TOKEN_REGISTRY,
+} from "../src/contracts/release-tokens.js";
+import {
+  ROUTE_REGISTRY,
+  ROUTE_RUNTIME_CONTRACT,
+} from "../src/features/installed-feature-contracts.js";
+
+const fixturesDocument =
+  /** @type {{
+   *   fixtures: Array<{
+   *     name: string,
+   *     expectedCompatible: boolean,
+   *     frontend: {
+   *       buildId: string,
+   *       configSchemaVersion: string,
+   *       apiContractVersion: string,
+   *       assetManifestHash: string,
+   *       releaseId: string
+   *     },
+   *     runtime: {
+   *       buildId: string,
+   *       configSchemaVersion: string,
+   *       apiContractVersion: string,
+   *       assetManifestHash: string,
+   *       releaseId: string
+   *     }
+   *   }>
+   * }} */ (
+    JSON.parse(
+      await readFile("config/release/coherence-fixtures.json", "utf8"),
+    )
+  );
+const release = JSON.parse(await readFile("dist/release-manifest.json", "utf8"));
+const runtimeConfig = JSON.parse(await readFile("dist/config.json", "utf8"));
+const buildManifest = JSON.parse(
+  await readFile("artifacts/release/build-manifest.json", "utf8"),
+);
+const runtimeConfigJsonSchema = JSON.parse(
+  await readFile("dist/runtime-config.schema.json", "utf8"),
+);
+const viteManifest = await readFile("dist/.vite/manifest.json", "utf8");
+const viteManifestObject =
+  /** @type {Record<string, {file: string, name?: string, isDynamicEntry?: boolean}>} */ (
+    JSON.parse(viteManifest)
+  );
+const actualAssetManifestHash = createHash("sha256")
+  .update(viteManifest)
+  .digest("hex");
+
+const artifactComparison = compareReleaseToRuntime(release, runtimeConfig);
+const artifactMismatches = [...artifactComparison.mismatches];
+for (const token of Object.keys(RELEASE_TOKEN_REGISTRY)) {
+  if (typeof release[token] !== "string" || release[token].length === 0) {
+    artifactMismatches.push(`releaseToken:${token}`);
+  }
+}
+if (!Number.isFinite(Date.parse(release.builtAt))) {
+  artifactMismatches.push("releaseToken:builtAtFormat");
+}
+if (release.assetManifestHash !== actualAssetManifestHash) {
+  artifactMismatches.push("assetManifestContent");
+}
+if (
+  runtimeConfigJsonSchema.$schema !== "https://json-schema.org/draft/2020-12/schema" ||
+  runtimeConfigJsonSchema.type !== "object" ||
+  !runtimeConfigJsonSchema.properties
+) {
+  artifactMismatches.push("runtimeConfigSchema");
+}
+if (
+  buildManifest.outputs?.runtimeConfigSchema !==
+  "dist/runtime-config.schema.json"
+) {
+  artifactMismatches.push("buildManifest:runtimeConfigSchema");
+}
+
+const expectedChunkIds = new Set(
+  Object.values(ROUTE_REGISTRY).map((definition) => definition.chunkId),
+);
+const actualChunkIds = new Set(Object.keys(release.routeChunks ?? {}));
+for (const chunkId of expectedChunkIds) {
+  if (!actualChunkIds.has(chunkId)) {
+    artifactMismatches.push(`routeChunk:missing:${chunkId}`);
+  }
+}
+for (const chunkId of actualChunkIds) {
+  if (!expectedChunkIds.has(chunkId)) {
+    artifactMismatches.push(`routeChunk:orphan:${chunkId}`);
+  }
+}
+for (const definition of Object.values(ROUTE_REGISTRY)) {
+  const runtime =
+    /** @type {Record<string, {moduleId: string}>} */ (
+      ROUTE_RUNTIME_CONTRACT
+    )[definition.routeId];
+  const viteEntry = Object.values(viteManifestObject).find(
+    (entry) => entry.name === runtime?.moduleId && entry.isDynamicEntry,
+  );
+  const routeAsset = release.routeChunks?.[definition.chunkId];
+  if (!runtime || !viteEntry || routeAsset !== viteEntry.file) {
+    artifactMismatches.push(`routeChunk:mismatch:${definition.chunkId}`);
+    continue;
+  }
+  if (
+    buildManifest.outputs?.routeChunks?.[definition.chunkId] !== routeAsset
+  ) {
+    artifactMismatches.push(`buildManifest:routeChunk:${definition.chunkId}`);
+  }
+  try {
+    await readFile(`dist/${routeAsset}`);
+  } catch {
+    artifactMismatches.push(`routeChunk:file:${definition.chunkId}`);
+  }
+}
+
+const fixtures = fixturesDocument.fixtures.map((fixture) => {
+  const result = verifyCompatibilityTuple({
+    frontend: fixture.frontend,
+    runtime: fixture.runtime,
+  });
+  return {
+    name: fixture.name,
+    expectedCompatible: fixture.expectedCompatible,
+    actualCompatible: result.compatible,
+    mismatches: result.mismatches,
+    passed: result.compatible === fixture.expectedCompatible,
+  };
+});
+const artifact = {
+  checked: true,
+  compatible: artifactComparison.compatible && artifactMismatches.length === 0,
+  mismatches: artifactMismatches,
+  releaseId: release.releaseId,
+};
+const passed = artifact.compatible && fixtures.every((fixture) => fixture.passed);
+const report = {
+  schemaVersion: 1,
+  generatedAt: new Date().toISOString(),
+  artifact,
+  fixtures,
+  passed,
+};
+
+await mkdir("artifacts/release", { recursive: true });
+await writeFile(
+  "artifacts/release/verification.json",
+  `${JSON.stringify(report, null, 2)}\n`,
+);
+
+if (!passed) {
+  process.stderr.write(
+    `Release coherence failed: ${artifactMismatches.join(", ") || "fixture"}\n`,
+  );
+  process.exit(1);
+}
+process.stdout.write(
+  `Release coherence: PASS (${fixtures.length - 1} mixed fixtures rejected)\n`,
+);

scripts/write-a11y-report.mjs

@@ -0,0 +1,20 @@
+import { mkdir, writeFile } from "node:fs/promises";
+
+import { MANUAL_A11Y_ROUTE_IDS } from "./lib/manual-a11y-evidence.mjs";
+
+await mkdir("artifacts/tests", { recursive: true });
+await writeFile(
+  "artifacts/tests/a11y.json",
+  `${JSON.stringify(
+    {
+      schemaVersion: 1,
+      generatedAt: new Date().toISOString(),
+      scope: MANUAL_A11Y_ROUTE_IDS,
+      threshold: { critical: 0, serious: 0 },
+      automatedStatus: "passed",
+      manualReview: "see artifacts/tests/a11y-manual/report.json",
+    },
+    null,
+    2,
+  )}\n`,
+);

src/adapters/auth/external-session-adapter.js

@@ -4,6 +4,9 @@
  *
  * @param {{
  *   readState(): import("../../application/ports/auth-session-port.js").SessionState,
+ *   subscribe(listener: () => void): () => void,
+ *   beginSignIn(returnTo?: string): Promise<void>,
+ *   signOut(): Promise<void>,
  *   attachCredential(request: Request): Promise<Request>,
  *   recoverSession(): Promise<"restored" | "no-session">,
  *   notifyUnauthenticated(): void
@@ -15,6 +18,16 @@ export function createExternalAuthSessionAdapter(owner) {
     getState() {
       return owner.readState();
     },
+    subscribe(listener) {
+      return owner.subscribe(listener);
+    },
+    async beginSignIn(returnTo) {
+      await owner.beginSignIn(returnTo);
+    },
+    async signOut() {
+      await owner.signOut();
+    },
+    /** @param {Request} request */
     async attach(request) {
       const attached = await owner.attachCredential(request);
       if (!(attached instanceof Request)) {
@@ -38,8 +51,74 @@ export function createExternalAuthSessionAdapter(owner) {
 export function createAnonymousSessionAdapter() {
   return createExternalAuthSessionAdapter({
     readState: () => "unauthenticated",
+    subscribe: () => () => {},
+    beginSignIn: async () => {},
+    signOut: async () => {},
     attachCredential: async (request) => request,
     recoverSession: async () => "no-session",
     notifyUnauthenticated: () => {},
   });
 }
+
+/**
+ * Local/test-only session seam. It never creates or stores credentials.
+ *
+ * @param {import("../../application/ports/auth-session-port.js").SessionState} [initialState]
+ */
+export function createDemoSessionAdapter(initialState = "unauthenticated") {
+  let state = initialState;
+  const listeners = new Set();
+
+  function notify() {
+    for (const listener of listeners) listener();
+  }
+
+  /** @param {import("../../application/ports/auth-session-port.js").SessionState} next */
+  function setState(next) {
+    state = next;
+    notify();
+  }
+
+  return Object.freeze({
+    getState: () => state,
+    /** @param {() => void} listener */
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    async beginSignIn() {
+      setState("authenticated");
+    },
+    async signOut() {
+      setState("unauthenticated");
+    },
+    /** @param {Request} request */
+    async attach(request) {
+      return request;
+    },
+    async recover() {
+      if (state === "recovery-pending") {
+        setState("authenticated");
+        return /** @type {const} */ ("restored");
+      }
+      return /** @type {const} */ ("no-session");
+    },
+    onUnauthenticated() {
+      setState("unauthenticated");
+    },
+    setState,
+  });
+}
+
+export function createUnavailableSessionAdapter() {
+  return Object.freeze({
+    getState: () => /** @type {const} */ ("integration-failed"),
+    subscribe: () => () => {},
+    beginSignIn: async () => {},
+    signOut: async () => {},
+    /** @param {Request} request */
+    attach: async (request) => request,
+    recover: async () => /** @type {const} */ ("no-session"),
+    onUnauthenticated: () => {},
+  });
+}

src/adapters/diagnostics/bounded-diagnostics.ts

@@ -0,0 +1,102 @@
+import type { DiagnosticsPort } from "../../application/ports/diagnostics-port.js";
+import {
+  projectDiagnosticRecord,
+  safeErrorKind,
+  type DiagnosticRecord,
+  type DiagnosticRecordInput,
+} from "../../contracts/diagnostics.js";
+import { projectTelemetryEvent } from "../../contracts/telemetry.js";
+
+export const noOpDiagnostics: DiagnosticsPort = Object.freeze({
+  record() {},
+});
+
+export function createDiagnosticsAdapter(
+  options: Readonly<{
+    maxEntries?: number;
+    now?: () => number;
+    sink?: (record: DiagnosticRecord) => void;
+  }> = {},
+) {
+  const maxEntries = Math.max(1, options.maxEntries ?? 100);
+  const entries: DiagnosticRecord[] = [];
+  const droppedReasons = new Map<string, number>();
+
+  function drop(reason: string) {
+    droppedReasons.set(reason, (droppedReasons.get(reason) ?? 0) + 1);
+  }
+
+  function record(input: DiagnosticRecordInput) {
+    try {
+      const projected = projectDiagnosticRecord(input, options.now);
+      if (!projected.success) {
+        drop(projected.reason);
+        return;
+      }
+      if (entries.length >= maxEntries) {
+        entries.shift();
+        drop("queue-full");
+      }
+      entries.push(projected.record);
+      try {
+        options.sink?.(projected.record);
+      } catch {
+        drop("sink-failure");
+      }
+    } catch {
+      drop("serialization-failure");
+    }
+  }
+
+  return Object.freeze({
+    record,
+    entries: () => structuredClone(entries) as readonly DiagnosticRecord[],
+    dropped: () => Object.freeze(Object.fromEntries(droppedReasons)),
+  });
+}
+
+type BootSafeContext = Readonly<{
+  kind?: string;
+  buildId?: string;
+  configSchemaVersion?: string;
+  supportReference?: string;
+}>;
+
+let lastBootEvidence:
+  | Readonly<{
+      diagnostic: DiagnosticRecord | null;
+      telemetry: Readonly<Record<string, unknown>> | null;
+    }>
+  | undefined;
+
+export function recordBootFailure(
+  error: unknown,
+  safe: BootSafeContext,
+  now: () => number = Date.now,
+) {
+  const errorKind =
+    typeof safe.kind === "string" ? safe.kind : safeErrorKind(error);
+  const attributes = {
+    error_kind: errorKind,
+    build_id: safe.buildId ?? "unknown",
+    config_schema_version: safe.configSchemaVersion ?? "unknown",
+  };
+  const diagnostic = projectDiagnosticRecord(
+    {
+      level: "error",
+      eventId: "app.boot.failed",
+      context: attributes,
+    },
+    now,
+  );
+  const telemetry = projectTelemetryEvent("app.boot.failed", attributes, now);
+  lastBootEvidence = Object.freeze({
+    diagnostic: diagnostic.success ? diagnostic.record : null,
+    telemetry: telemetry.success ? telemetry.event : null,
+  });
+  return lastBootEvidence;
+}
+
+export function getLastBootEvidence() {
+  return lastBootEvidence ? structuredClone(lastBootEvidence) : undefined;
+}