Carries 359 template commits, tag v0.2.0 plus one documentation commit: the generator-built feature index with its app, bounded-context and feature declarations, the src/platform kernel and scale tooling, the 2026-09-24 src review fixes, and the 2026-09-25 maturity review round with its CHANGELOG [보안]/[계약] rows. 691 of the 824 template paths are applied, 85 of them merged with product changes; 127 are not carried. Product identity is unchanged: name, version 0.1.0, routes, design and the TechLog domain. Three decisions worth naming. TechLog stays composed directly, as the last two syncs recorded; its directory carries a NOT_INSTALLED marker that says so, and every installed-* composer takes the template's projection with TechLog added on top. The reference sample is no longer installed: the template now installs a feature only through feature-module.ts and context-routes.ts, which load the screens this product deleted, so its three operations, six schemas and one topic leave the registries, recorded as registry change evidence. And AppRouter mounts the platform and TechLog routes only; the template's bounded-context route gateway waits for a generator-installed feature. Required fixes: readSubject on the BFF session owner (without it every HTTP Studio session would close as integration-failed), zod through the facade in nine TechLog files, noUnusedLocals, and public/config.json written out to match the local profile. Derived baselines were recomputed after reproducing both sides' values: CI contract 101 commands / 106 references / 141 artifacts, gate shape c9adcf85; registry approval 2dc6c3a3; the runtime config schema baseline equals the schema at8210d48. Verified here: types, lint, architecture, adapter inventory, CI contract, i18n, design system, diagnostics, browser security, dev release manifest, TechLog contract and build pass; 220 component, 155 integration, 15 contract, 418 TechLog, 43 reference-feature, 18 recipe and 46 release-coherence tests pass, and 2381 of 2383 unit tests. Reproduced at8210d48first and unchanged: check:registries (byte-identical), test:runtime-schema, verify:documentation. Brought by the template and escalated rather than suppressed: check:request-fanout on TechLog's cursor pagination, check:remediation-ledger (fails upstream too), the shared-chunk hash test, and the registry-dependent sample removal and second-feature tests. Playwright suites were not run. Full record, the five open questions and the follow-ups in docs/operations/template-sync-2026-09-29.md. (cherry picked from commit b2170cf265dea45dc9cc05d3c61e627e97f31cdb)
452 lines
24 KiB
Markdown
452 lines
24 KiB
Markdown
# Tech Log Frontend
|
|
|
|
Initialized from `clean-architecture-frontend-template` revision
|
|
`4dc033cf33a5b6173bbf960d5eb464a406dc4c92`. The exact source identity is
|
|
recorded in `template.lock.json`.
|
|
|
|
A React/Vite TechLog application where architecture boundaries, integration
|
|
behavior, release coherence, accessibility, performance, and operations are
|
|
executable contracts rather than conventions.
|
|
|
|
## Start locally
|
|
|
|
Requirements: the exact Node.js version in `.nvmrc` (currently 24.14.0) and
|
|
Corepack. The repository pins pnpm in `package.json`.
|
|
|
|
Product source, tests, build/quality scripts, and supported tool configuration
|
|
are TypeScript/TSX. `allowJs` is disabled. Node-side `.ts` scripts run directly
|
|
on the pinned Node 24 runtime and are checked with NodeNext resolution plus
|
|
erasable-syntax enforcement. Project-owned executable source contains no
|
|
JavaScript-family files; negative architecture, security, and type-compatibility
|
|
fixtures are TypeScript/TSX as well.
|
|
|
|
```bash
|
|
corepack pnpm install --frozen-lockfile
|
|
corepack pnpm dev
|
|
```
|
|
|
|
## Runtime configuration
|
|
|
|
Runtime-public settings are validated against one schema before the product
|
|
tree mounts (`runtimeConfigV2ArtifactSchema` in
|
|
`src/contracts/release-artifacts.ts`). Client secrets are forbidden.
|
|
|
|
The source of truth is `config/runtime/<profile>.json`, one file per
|
|
environment: `local`, `development`, `staging`, `production`. `corepack pnpm
|
|
build` writes `dist/config.json` from the selected profile
|
|
(`scripts/generate-runtime-config.ts`). `public/config.json` is only the local
|
|
profile for `corepack pnpm dev`; the build replaces it, so settings put there
|
|
never reach a deployment. Keep it equal to `config/runtime/local.json` plus
|
|
`BUILD_ID: local-build` and `RELEASE_ID: local-release`;
|
|
`tests/unit/deployment-admission.test.ts` fails when the two differ.
|
|
|
|
Build and deploy variables, lowest precedence first:
|
|
|
|
| Variable | Sets | Default |
|
|
| --- | --- | --- |
|
|
| `APP_PROFILE` | which `config/runtime/<profile>.json` is used | `local`; an empty value fails the build |
|
|
| `RUNTIME_API_BASE_URL` | `API_BASE_URL`, overriding the profile | the profile value |
|
|
| `RUNTIME_TELEMETRY_ENDPOINT` | `TELEMETRY_ENDPOINT`, overriding the profile | the profile value |
|
|
| `VITE_BUILD_ID` | `BUILD_ID` in the runtime config and the release manifest | `local-build` |
|
|
| `RELEASE_ID` | `RELEASE_ID` in the runtime config and the release manifest | `local-release` |
|
|
| `RELEASE_TARGET` | the environment FE-GATE-027 admits the build to; must equal `APP_PROFILE` | none; admission refuses without it |
|
|
|
|
`verify:documentation` fails if this table stops naming a variable the build or
|
|
admission reads (`scripts/verify-documentation-readiness.ts`).
|
|
|
|
Only the two `RUNTIME_*` values can differ from the reviewed profile. Anything
|
|
else changes by editing the profile file. Staging and production reject demo
|
|
auth and non-HTTPS endpoints.
|
|
|
|
A production build and its admission check:
|
|
|
|
```bash
|
|
APP_PROFILE=production \
|
|
RUNTIME_API_BASE_URL=https://api.example.com/ \
|
|
RUNTIME_TELEMETRY_ENDPOINT=https://telemetry.example.com/v1/events \
|
|
VITE_BUILD_ID=<unique build id> RELEASE_ID=<unique release id> \
|
|
corepack pnpm build
|
|
APP_PROFILE=production RELEASE_TARGET=production corepack pnpm check:release-admission
|
|
```
|
|
|
|
With `CI=true` the gate runner (`corepack pnpm ci:gate`) also requires
|
|
`VITE_COMMIT_SHA`, `SOURCE_DATE_EPOCH` and `CI_RUNNER_IMAGE` before it runs a
|
|
gate (`scripts/lib/build-environment.ts`, `scripts/run-ci-gate.ts`). The CI variable
|
|
list is in [`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md).
|
|
|
|
## TechLog experience
|
|
|
|
The default build mounts the source-faithful TechLog Public and Studio
|
|
experience. Public routes provide discovery, search, documents, topics,
|
|
projects, releases, and profile content. `/studio` provides the session-scoped
|
|
mock authoring workflow: create, edit, validate, preview, publish, unpublish,
|
|
and immutable publication history.
|
|
|
|
The 27 canonical route definitions are divided into `PUBLIC` and `STUDIO`
|
|
nested layouts. Studio authentication remains deliberately deferred; its mock
|
|
gateway state lasts for one Studio shell session and resets on a full document
|
|
load. The exact route, dependency, stylesheet, asset, and parity inventory is
|
|
recorded in
|
|
[`docs/operations/techlog-ui-migration-baseline.md`](docs/operations/techlog-ui-migration-baseline.md).
|
|
|
|
`corepack pnpm build` emits a self-contained `dist/server.mjs` production
|
|
boundary. `corepack pnpm preview --host 127.0.0.1 --port 4174` serves known
|
|
Public and Studio routes as SPA documents, preserves the in-shell Studio 404,
|
|
and returns source-exact raw `404 text/plain` responses for missing Public
|
|
content. With the read-only source temp-copy server on `4375`, run:
|
|
|
|
```bash
|
|
TECH_LOG_SOURCE_URL=http://127.0.0.1:4375 \
|
|
TECH_LOG_TARGET_URL=http://127.0.0.1:4174 \
|
|
corepack pnpm verify:tech-log-source-parity
|
|
```
|
|
|
|
### Studio backend source
|
|
|
|
`TECH_LOG_STUDIO_SOURCE` (`MOCK` | `HTTP`) selects which `StudioGateway`
|
|
adapter the composition root wires up. It defaults to `MOCK` — the
|
|
session-scoped in-memory Studio described above — so the existing Studio
|
|
workflow and its test suites are unaffected unless the switch is deliberately
|
|
turned on. Setting it to `HTTP` wires the HTTP `StudioGateway` instead, which
|
|
calls the canonical `@tech-log/studio-contract` operations against
|
|
`API_BASE_URL`. With no backend reachable at that URL, Studio still boots and
|
|
its shell renders; the specific panels that need the backend show an inline
|
|
"failed to load" state rather than a blank screen or an unhandled exception.
|
|
|
|
The switch is a field on the versioned runtime config document
|
|
(`RuntimeConfigV2`), not a build-time flag:
|
|
|
|
- `config/runtime/{local,development,staging,production}.json` are the
|
|
deployment profiles `corepack pnpm build` (via
|
|
`scripts/generate-runtime-config.ts`) materializes into `dist/config.json`
|
|
for a real build.
|
|
- `corepack pnpm dev` does not run that step. Plain `vite` serves
|
|
`public/config.json` (and `public/release-manifest.json`) verbatim as dev
|
|
fixtures — editing `config/runtime/local.json` alone has no effect on
|
|
`pnpm dev`. To exercise `HTTP` mode under `pnpm dev`, set
|
|
`TECH_LOG_STUDIO_SOURCE` in `public/config.json` directly.
|
|
|
|
### The dev release manifest must declare the compiled contract set
|
|
|
|
Contract-set verification runs unconditionally at boot, before any adapter is
|
|
selected. It is not an `HTTP`-mode caveat: if `public/release-manifest.json`'s
|
|
`contractSet` does not match the set the build compiled, `corepack pnpm dev`
|
|
does not start the app at all — it renders the fail-closed boot screen
|
|
(`CONTRACT_SET_MISMATCH` / `CONTRACT_SET_PACKAGE_MISSING`) in the **default
|
|
`MOCK` mode** too. A developer who runs `pnpm dev` and gets a boot error has a
|
|
broken dev server, however tidy the screen looks; treat it as a defect in the
|
|
fixture, never as expected behaviour.
|
|
|
|
The expectation comes from `EXPECTED_CONTRACT_SET_PACKAGES`
|
|
(`src/features/installed-contract-contributions.ts`), and a real build writes it
|
|
into `dist/release-manifest.json` from `scripts/generate-contract-set.ts`, so
|
|
production builds are always self-consistent. Only the hand-maintained dev
|
|
fixture can drift, and it drifts whenever either half moves — a regenerated
|
|
contract (new package digest or version) or a contribution added to or removed
|
|
from `installed-contract-contributions.ts`. Two things keep it honest:
|
|
|
|
- `corepack pnpm generate:tech-log-contract` refreshes the fixture's
|
|
`contractSet` block as its last step, so regenerating the contract can never
|
|
leave the two out of step. `corepack pnpm generate:dev-release-manifest`
|
|
refreshes the same block on its own, for the contribution-list case that does
|
|
not go through contract generation.
|
|
- `corepack pnpm check:dev-release-manifest` is the gate. It compares the
|
|
fixture's `setAlgorithm`, `setDigest` and package set against the compiled
|
|
set and fails on any difference. It runs in CI as part of FE-GATE-010, which
|
|
is what catches the changes the generation step cannot see.
|
|
|
|
### TechLog contract generation
|
|
|
|
The Studio HTTP contract is vendored from a canonical OpenAPI source, not
|
|
hand-written:
|
|
|
|
- `corepack pnpm generate:tech-log-contract` regenerates
|
|
`src/features/tech-log/contracts/studio/studio-api.openapi.yaml`,
|
|
`generated.ts`, and `canonical-source.json` from the canonical
|
|
`tech-log-design-package` repository (path from `TECH_LOG_DESIGN_PACKAGE`,
|
|
default `/home/donghyeon/workspace/tech-log-design-package`). It needs that
|
|
repository checked out locally and network access, because type generation
|
|
runs in an isolated `pnpm dlx` sandbox (this repo pins TypeScript 7, which
|
|
has no classic compiler API for `openapi-typescript` to use). Run it after
|
|
the canonical contract changes, then commit the regenerated files.
|
|
- `corepack pnpm check:tech-log-contract` is the drift gate: it hashes the
|
|
vendored yaml against the recorded digest and confirms every recorded
|
|
`operationId` is present in both the yaml and the generated types. It needs
|
|
neither the canonical repository nor the network, so it runs in CI and in
|
|
this sandbox. Run it any time to confirm the vendored contract has not
|
|
drifted from what was last generated.
|
|
|
|
## Support scope
|
|
|
|
Four tiers. The status words on the right are the ones the catalogs and
|
|
design documents use; the next table maps them.
|
|
|
|
| Tier | What it covers | Status words |
|
|
| --- | --- | --- |
|
|
| Default | In the default build and covered by the merge gates: the TechLog Public and Studio shells and routes, the REST HTTP executor, TanStack Query server state, Local/Session Storage registries, cross-tab invalidation, runtime config profiles and the release manifest check, `AUTH_MODE=external` (`demo` only in local/development), and the typed message catalog. `dist/` is served by a static host ([`docs/architecture/static-delivery.md`](docs/architecture/static-delivery.md)) | `COMPOSED` |
|
|
| Optional (recipe) | Not installed. A project copies one of the recipes in `config/recipes/frontend-capability-recipes.json` and narrows it ([`docs/architecture/optional-adapter-recipes.md`](docs/architecture/optional-adapter-recipes.md)). `realtime`, `offline-indexeddb`, `service-worker-pwa` and `file-transfer` also ship a tested reference runtime that the default build leaves out | `RECIPE_AVAILABLE`, `NOT_INSTALLED`, `AVAILABLE_NOT_COMPOSED` |
|
|
| Experimental | Designed and decided, but the runtime is missing or unfinished; finish it before building on it. GraphQL, gRPC-Web, Connect-Web and Protobuf adapters, Range resumable download, IndexedDB query persistence, the local preview decode-safety probe. `src/features/local-draft-feature` is an architecture sample, not installed; so is `src/features/reference-feature`, the template's removable sample, whose screens this product deleted | `DESIGNED_NOT_IMPLEMENTED` |
|
|
| Not supported | Deliberately not selected, or browsers cannot guarantee it: SSR, app-managed background upload and download, directory selection, persistent file handles, product query persistence, exactly-once delivery between tabs | `NOT_SELECTED`, `PLATFORM_LIMITED` |
|
|
|
|
The rows come from
|
|
[`docs/architecture/browser-data-capability-completion-ledger.md`](docs/architecture/browser-data-capability-completion-ledger.md),
|
|
[`docs/architecture/client-cache-and-storage.md`](docs/architecture/client-cache-and-storage.md)
|
|
and
|
|
[`docs/architecture/api-contract-schema-mapper-and-server-state.md`](docs/architecture/api-contract-schema-mapper-and-server-state.md).
|
|
|
|
| Status word | Where it appears | Meaning | Tier |
|
|
| --- | --- | --- | --- |
|
|
| `COMPOSED` | capability ledger, design documents | wired into the default production path | Default |
|
|
| `INSTALLED` | a project's own recipe catalog (step 10 of the recipe procedure) | the project added the recipe | Default, for that project |
|
|
| `RECIPE_AVAILABLE` | recipe catalog `status` | a recipe exists to copy; nothing is installed | Optional |
|
|
| `NOT_INSTALLED` | recipe catalog `defaultStatus`; a `src/features/<id>/NOT_INSTALLED` marker file | not part of the build | Optional (recipe) or Experimental (feature) |
|
|
| `AVAILABLE_NOT_COMPOSED` | capability ledger; recipe `referenceRuntime.status` | code and tests exist; the default build leaves it out | Optional |
|
|
| `DESIGNED_NOT_IMPLEMENTED` | capability ledger, design documents | design approved, runtime missing | Experimental |
|
|
| `NOT_SELECTED` | capability ledger, design documents | deliberately not chosen | Not supported |
|
|
| `PLATFORM_LIMITED` | capability ledger | browsers cannot guarantee it; offered only behind a probe and a fallback, if at all | Not supported as a guarantee |
|
|
|
|
Gate results (`PASS`, `PASS_SCOPED`, `UNVERIFIED`, `FAIL_UNVERIFIED`) are
|
|
verdicts on evidence, not support tiers.
|
|
|
|
Browsers: the build targets Chrome and Edge 111, Firefox 128, and Safari and
|
|
iOS 16.4. That is the higher of Vite 8's default JavaScript target
|
|
(`baseline-widely-available`; `vite.config.ts` sets no `build.target`) and
|
|
the CSS targets of Tailwind CSS 4. There is no browserslist. The end-to-end
|
|
suite runs on the desktop Chromium, Firefox and WebKit builds that Playwright
|
|
1.62 pins, plus one Chromium phone-size smoke (`playwright.config.ts`). Older
|
|
versions inside the target range and real mobile browsers are not tested.
|
|
|
|
## Architecture
|
|
|
|
This repository is a **Frontend Application Foundation**: a starter/composition
|
|
skeleton plus a reusable capability platform. Platform capabilities stay
|
|
horizontal while product business features use vertical slices.
|
|
|
|
Dependencies point inward:
|
|
|
|
```text
|
|
presentation -> application -> domain
|
|
adapters -----^
|
|
bootstrap composes concrete adapters
|
|
feature use case -> feature port <- feature-owned capability binding
|
|
```
|
|
|
|
See
|
|
`docs/architecture/frontend-application-foundation.md`,
|
|
`docs/architecture/overview.md`, `docs/architecture/layers.md`, and
|
|
`docs/architecture/starter-experience.md`. TechLog is one feature boundary
|
|
under `src/features/tech-log`. Its immutable Public catalog and session-scoped
|
|
Studio mock gateway are injected through the application feature input;
|
|
Public and Studio presentation code shares the typed content renderer without
|
|
importing concrete adapters. The retained reference feature remains a
|
|
non-product platform contract fixture and can be removed without changing the
|
|
TechLog route set.
|
|
|
|
### 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)
|
|
- [REST, GraphQL, Connect/gRPC-Web, Schema, Mapper, and Server State](docs/architecture/api-contract-schema-mapper-and-server-state.md)
|
|
- [Protobuf browser transports and REST Gateway](docs/architecture/protobuf-browser-transport-and-rest-gateway.md)
|
|
- [backend API and Server State handoff contract](docs/architecture/backend-api-and-server-state-contract.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)
|
|
- [browser data capability completion ledger](docs/architecture/browser-data-capability-completion-ledger.md)
|
|
- [browser file and origin-storage platform](docs/architecture/browser-file-and-origin-storage.md)
|
|
- [client cache and storage](docs/architecture/client-cache-and-storage.md)
|
|
- [realtime events, Web Push, and bounded polling](docs/architecture/realtime-events-web-push-and-bounded-polling.md)
|
|
- [presigned transfer, resumable upload, streaming download, and Image CDN](docs/architecture/presigned-transfer-and-image-cdn.md)
|
|
- [server file capability infrastructure](docs/architecture/server-file-capability-infrastructure.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.
|
|
|
|
## Documentation
|
|
|
|
[`docs/README.md`](docs/README.md) sorts the documents into current contracts,
|
|
target designs and work history.
|
|
|
|
### Files you can delete after copying
|
|
|
|
These record how the template and this product were built. Nothing in the
|
|
build or the gates reads them, except the one file noted below
|
|
(`tests/unit/deletable-history-documents.test.ts` checks this).
|
|
|
|
| Path | Contents |
|
|
| --- | --- |
|
|
| `docs/superpowers/` | past plans and specs |
|
|
| `docs/reviews/` | reviews. Keep `docs/reviews/adapters/INVENTORY.md`: `check:adapter-inventory` (FE-GATE-010) reads it |
|
|
|
|
The template's own `SPEC.md`, `tasks/` and `CLAUDE.md` were never carried
|
|
into this repository (`docs/operations/template-sync-2026-09-29.md`).
|
|
|
|
The reference feature is not in this list: deleting its directory alone
|
|
leaves tests, policy entries and CI scripts behind that fail the gates.
|
|
`scripts/test-sample-removal.ts` removes it from a copy of
|
|
the repository and lists everything that has to go with it (its header comment
|
|
and `SAMPLE_EXTRAS`); do the same in your project and run the gates.
|
|
|
|
## Verification
|
|
|
|
Common local checks:
|
|
|
|
```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:contract
|
|
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
|
|
corepack pnpm exec vitest run tests/features/tech-log
|
|
corepack pnpm exec playwright test tests/e2e/tech-log-public-discovery.spec.ts tests/e2e/tech-log-studio-workflow.spec.ts tests/e2e/tech-log-responsive.spec.ts tests/e2e/tech-log-accessibility.spec.ts --project=chromium
|
|
corepack pnpm test:visual
|
|
```
|
|
|
|
`drill:runbooks` stops at the first drill that is not `PASS`. Without provider
|
|
evidence every drill ends `UNVERIFIED` (exit 3), because a drill never reports
|
|
a check it could not run locally as `PASS`; see "Runbook jobs" in
|
|
[`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md).
|
|
|
|
`test:all` is the ordinary product-development loop and intentionally excludes
|
|
host-level CI-runner assurance. Run `corepack pnpm test:system` only on the
|
|
compatible Linux assurance host described in
|
|
[`docs/testing/taxonomy.md`](docs/testing/taxonomy.md).
|
|
|
|
`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)에 기록돼
|
|
있다.
|
|
|
|
Application feature input은 module augmentation으로 닫힌 ID와 정확한 input
|
|
shape를 제공하며, 공통 `Result<Value, Failure = AppFailure>`는 error registry의
|
|
failure kind만 application/presentation 경계를 통과시킨다. Architecture gate는
|
|
TypeScript/TSX의 static, dynamic, type import를 별도 정적 그래프로 분석하고
|
|
runtime/source 영역의 JavaScript 재유입도 거절한다. 해석되지 않은 import,
|
|
parse failure, 금지 계층 edge와 순환 의존은 모두 fail-closed이며 전용
|
|
TypeScript/TSX negative fixture로도 검증된다.
|
|
|
|
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` (release gate FE-GATE-028) needs a signed human
|
|
keyboard/focus/screen-reader review for all 27 registered routes:
|
|
`NOT_FOUND`, `TECH_LOG_CASE`, `TECH_LOG_EXPLORE`, `TECH_LOG_EXPLORE_KIND`,
|
|
`TECH_LOG_HOME`, `TECH_LOG_PROFILE`, `TECH_LOG_PROJECT`,
|
|
`TECH_LOG_PROJECTS`, `TECH_LOG_PROJECT_ACTIVITY`,
|
|
`TECH_LOG_PROJECT_DECISIONS`, `TECH_LOG_PROJECT_RECORDS`,
|
|
`TECH_LOG_QUESTION`, `TECH_LOG_REFERENCE`, `TECH_LOG_RELEASE`,
|
|
`TECH_LOG_RELEASES`, `TECH_LOG_SEARCH`, `TECH_LOG_STUDIO_DOCUMENTS`,
|
|
`TECH_LOG_STUDIO_DOCUMENT_EDIT`, `TECH_LOG_STUDIO_DOCUMENT_NEW`,
|
|
`TECH_LOG_STUDIO_DOCUMENT_PREVIEW`, `TECH_LOG_STUDIO_DOCUMENT_PUBLISH`,
|
|
`TECH_LOG_STUDIO_DOCUMENT_VALIDATION`, `TECH_LOG_STUDIO_HOME`,
|
|
`TECH_LOG_STUDIO_NOT_FOUND`, `TECH_LOG_STUDIO_PUBLICATIONS`,
|
|
`TECH_LOG_STUDIO_PUBLICATION_PREVIEW`, `TECH_LOG_TOPIC`.
|
|
`verify:documentation` derives that list from the route registry and fails if
|
|
this paragraph falls behind it. The merge gate FE-GATE-009 runs only
|
|
`review:a11y-manual -- --format-only`, which checks that every route record
|
|
keeps the template's fields, reviewed or still pending.
|
|
- `collect:web-vitals-evidence` stays `FAIL_UNVERIFIED` until a reviewed minimum
|
|
eligible-sample threshold and 28 days of production data exist.
|
|
|
|
Live hosting verification (FE-GATE-019, production stage) requires
|
|
`HOSTING_BASE_URL` and a deployed promoted release; without it the result is
|
|
`UNVERIFIED`, not `PASS`.
|
|
|
|
## CI and evidence
|
|
|
|
The 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.
|
|
|
|
The workflow runs on pull requests, pushes to `main`, and `v*` tags. The Git host of this repository may not have Actions enabled, so a pull
|
|
request can show no gate status at all; no status is not a pass. Until the
|
|
host runs the workflow and marks the merge gates as required checks, run the 13
|
|
merge gates locally before merging (FE-GATE-008 and 009 need Playwright
|
|
browsers):
|
|
|
|
```bash
|
|
for gate in 001 002 003 004 005 006 007 008 009 010 011 013 020; do
|
|
corepack pnpm ci:gate -- "FE-GATE-$gate" || break
|
|
done
|
|
```
|
|
Machine-readable evidence is written below `artifacts/`; generated evidence is
|
|
ignored by Git while `.gitkeep` files preserve the taxonomy.
|
|
|
|
Operational details are in `docs/operations/`, with incident procedures in
|
|
`docs/runbooks/`.
|
|
|
|
## Updating a copied project
|
|
|
|
Template versions are Git tags `vX.Y.Z`. The template repository's
|
|
`CHANGELOG.md` lists the changes between tags, marks security fixes **[보안]** and contract changes
|
|
**[계약]** (backend, deployment, CI or feature code must change too), and names
|
|
the affected paths.
|
|
|
|
Record where you started. The template suggests a one-line `.template-origin`
|
|
file; this repository records the same thing, more precisely, in
|
|
`template.lock.json` (`sourceRevision` and `sourceTree`), and every sync is
|
|
written up in `docs/operations/template-sync-*.md`.
|
|
|
|
Take a template fix with Git. `cherry-pick` works even when your repository
|
|
does not share the template's history, because it merges against the picked
|
|
commit's parent:
|
|
|
|
```bash
|
|
git remote add template <template repository URL>
|
|
git fetch template --tags
|
|
git log --oneline <your origin>..template/main # what changed since you copied
|
|
git cherry-pick -x <commit> # one fix; -x records its origin
|
|
```
|
|
|
|
When the files have moved or diverged too far for a clean pick, read the
|
|
change as a diff and apply it by hand:
|
|
|
|
```bash
|
|
git diff <commit>^ <commit> -- <paths from CHANGELOG>
|
|
```
|
|
|
|
Afterwards run the local merge gates from "CI and evidence", apply the
|
|
backend or deployment change a **[계약]** row names, and update
|
|
`template.lock.json` once you have caught up to a tag. `git revert` undoes a pick.
|
|
|
|
Defects: if a problem reproduces on an unmodified checkout of the template at
|
|
`template.lock.json`'s `sourceRevision`, it is a template defect. Report it on the template
|
|
repository with that commit and the reproduction; the template maintainer
|
|
classifies it and ships the fix with a CHANGELOG entry. A problem that needs
|
|
your changes to reproduce belongs to your project, and applying a template fix
|
|
to your copy is your project's job.
|