From 4ab35c4a0512d27e24d2cdcc90519ec6c9f78243 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 12 Nov 2026 22:32:09 +0900 Subject: [PATCH 01/28] =?UTF-8?q?fix(test):=20=ED=85=9C=ED=94=8C=EB=A6=BF?= =?UTF-8?q?=20=EC=8B=9C=ED=97=98=EC=9D=B4=20=EC=82=AC=EB=B3=B8=EC=97=90=20?= =?UTF-8?q?=EB=A7=8C=EB=93=9C=EB=8A=94=20=EA=B8=B0=EB=8A=A5=20ID=EB=A5=BC?= =?UTF-8?q?=20=EC=98=88=EC=95=BD=20=EC=A0=91=EB=91=90=EC=96=B4=EB=A1=9C=20?= =?UTF-8?q?=EC=98=AE=EA=B8=B4=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 템플릿 시험과 드릴이 저장소 사본에 고정 ID로 기능을 만든다. 매뉴얼 코드 조각 시험은 매뉴얼 예시 invoice-feature를(FE-GATE-005), 생성 기능 e2e·청크 복구·부팅 실패 spec은 order-feature를(FE-GATE-008), scaffold 드릴은 scaffold-feature를(FE-GATE-020) 쓴다. 사본에는 제품 기능이 들어 있고 create:feature는 같은 ID나 같은 접두어를 거부한다. 그래서 매뉴얼 1단계 예시대로 invoice-feature를 만든 제품은 기능 코드와 상관없이 merge 게이트에서 막힌다. 고른 방법: 사본에 만드는 기능 ID를 모두 이미 정한 예약 접두어 typecheck-probe-로 옮기고 scripts/lib/template-probe-features.ts 한 곳에 둔다. 매뉴얼 조각은 invoice-feature 기준 그대로 두고, 시험이 조각과 검사 파일의 이름(INVOICE_, Invoice, invoice-, invoice)을 예약 기능의 이름으로 바꿔 넣는다(renameFeatureText). 생성 기능 e2e는 메시지 키와 계약 이름을 ID에서 만든다. 버린 대안: 사본에서 제품의 같은 이름 기능을 먼저 지우기(등록·조립 파일까지 지워야 해 사본이 제품과 달라진다), create:feature가 흔한 이름을 거부하기(제품 이름을 막는다). 위험·한계: 이름 바꾸기는 낱말 단위 치환이라 조각의 영어 문장 속 invoice도 바뀐다(조각과 검사가 함께 바뀌어 결과는 같다). 제품이 typecheck-probe-로 시작하는 기능을 만들면 다시 부딪친다. 매뉴얼과 create-feature 참조에 쓰지 말라고 적었고 생성 명령이 막지는 않는다. measure-feature-shape-growth의 s000-feature 꼴 ID는 그대로 뒀다. 검증: desktop에서 RED(이 커밋의 시험을 기준 커밋에 얹음)와 GREEN, 제품 상태(invoice-feature·order-feature를 만든 사본)의 FE-GATE-005·008 재현은 PR 본문에 적는다. Refs: 1112/08-02 --- docs/manual/01-add-a-feature.md | 3 +- docs/manual/02-decision-tables.md | 2 +- docs/manual/reference/create-feature.md | 4 +- docs/work/new-feature.md | 2 +- docs/work/reference/defect-patterns.md | 2 +- docs/work/reference/testing.md | 2 +- scripts/create-feature.ts | 2 +- scripts/lib/generated-feature.ts | 40 ++++--- scripts/lib/template-probe-features.ts | 49 ++++++++ scripts/test-feature-scaffold.ts | 9 +- scripts/test-sample-removal.ts | 3 +- tests/e2e/generated-feature.spec.ts | 23 ++-- tests/unit/manual-code-blocks.test.ts | 19 ++- ...template-feature-removal-documents.test.ts | 13 ++- tests/unit/template-probe-features.test.ts | 109 ++++++++++++++++++ 15 files changed, 239 insertions(+), 43 deletions(-) create mode 100644 scripts/lib/template-probe-features.ts create mode 100644 tests/unit/template-probe-features.test.ts diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index d298aeb7..f0ce2bd3 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -10,7 +10,7 @@ 생성 명령은 이 문제를 미리 피한 파일을 쓴다. 템플릿에는 복사해 볼 기능 샘플이 없다. 생성 뼈대에 없는 모양은 이 매뉴얼 안의 코드 조각으로 보인다. 코드 조각 위의 `manual-code-block` 표식이 그 조각을 둘 자리다. 조각은 `create:feature invoice-feature --with-create`로 만든 기능을 기준으로 쓴다. -`tests/unit/manual-code-blocks.test.ts`가 그 기능을 저장소 사본에 만들고 조각을 그 자리에 그대로 넣어 타입 검사와 동작 시험을 돌린다. +`tests/unit/manual-code-blocks.test.ts`가 저장소 사본에 예약 이름의 같은 기능(`typecheck-probe-invoice-feature`)을 만들고, 조각의 이름만 그 기능 이름으로 바꿔 그 자리에 넣은 뒤 타입 검사와 동작 시험을 돌린다. 사본에 제품이 만든 `invoice-feature`가 있어도 부딪치지 않는다. ## 전체 흐름 @@ -72,6 +72,7 @@ - `ApplicationFeatureInputs`의 키 - `config/runtime/.json`의 `FEATURE_OVERRIDES` 키 - ID가 `-feature`로 끝나면 생성 명령은 그 앞부분을 접두어로 쓴다. `invoice-feature`면 `invoice`, `INVOICE_`, `Invoice`다. +- `typecheck-probe-`로 시작하는 ID는 쓰지 않는다. 템플릿 시험이 저장소 복사본에 만드는 기능 이름이다(`scripts/lib/template-probe-features.ts`). 그 밖의 이름은 이 매뉴얼의 예시(`invoice-feature`)를 포함해 모두 쓸 수 있다. - 근거: `scale-architecture.md` §5(모듈 소유), §7(개수 예산), §9(라우터 구조). ③ **잡는 검사 / 못 잡는 것** diff --git a/docs/manual/02-decision-tables.md b/docs/manual/02-decision-tables.md index 145996e6..56da9ac5 100644 --- a/docs/manual/02-decision-tables.md +++ b/docs/manual/02-decision-tables.md @@ -326,7 +326,7 @@ export function mapInvoiceCreateProblem( } ``` -- 이 두 조각은 `tests/unit/manual-code-blocks.test.ts`가 시험한다. 저장소 사본에 `create:feature invoice-feature --with-create`로 기능을 만들고, 조각을 위 경로에 그대로 넣어 타입 검사를 하고, 분류와 매핑이 위 설명대로인지 돌려 본다(`tests/fixtures/manual-code-blocks/`). +- 이 두 조각은 `tests/unit/manual-code-blocks.test.ts`가 시험한다. 저장소 사본에 예약 이름의 같은 기능(`typecheck-probe-invoice-feature`)을 `--with-create`로 만들고, 조각의 이름만 그 기능 이름으로 바꿔 위 경로에 넣어 타입 검사를 하고, 분류와 매핑이 위 설명대로인지 돌려 본다(`tests/fixtures/manual-code-blocks/`). **틀리면** diff --git a/docs/manual/reference/create-feature.md b/docs/manual/reference/create-feature.md index c57895af..dc754a5c 100644 --- a/docs/manual/reference/create-feature.md +++ b/docs/manual/reference/create-feature.md @@ -12,7 +12,7 @@ corepack pnpm create:feature [--context ] [--with-create [--key | 인자 | 규칙 | |---|---| -| `` | 케밥 표기, 40자 이하. 기존 기능·context ID와 겹치면 거부 | +| `` | 케밥 표기, 40자 이하. 기존 기능·context ID와 겹치면 거부. `typecheck-probe-`로 시작하는 ID는 템플릿 시험이 복사본에 만드는 이름이라 쓰지 않는다(`scripts/lib/template-probe-features.ts`) | | `--context` | 기존 context ID. 없으면 `-context`를 새로 만든다 | | `--with-create` | 짝 백엔드 `new-feature.sh`의 작성(`POST /`)·상세(`GET //{id}`)와 그 페이지를 더한다. 작성은 `NEVER` | | `--keyed` | `--with-create`와 함께만. 작성을 `KEYED`로 만든다. 백엔드 create를 멱등성 executor 뒤에 둔 뒤에 쓴다 | @@ -164,5 +164,5 @@ node scripts/write-dev-release-manifest.ts # dev manifest에서 그 기능의 ## 알려진 한계 -- 드릴은 브라우저 테스트(FE-GATE-008·009의 `test:e2e`, `test:a11y` 등)와 `test:system`을 돌리지 않는다. `check:bundle`(FE-GATE-012)은 돈다. 브라우저에서의 동작은 위 e2e spec이 고정한 이름(`order-feature`)의 기능 하나로만 본다. +- 드릴은 브라우저 테스트(FE-GATE-008·009의 `test:e2e`, `test:a11y` 등)와 `test:system`을 돌리지 않는다. `check:bundle`(FE-GATE-012)은 돈다. 브라우저에서의 동작은 위 e2e spec이 고정한 이름(`typecheck-probe-order-feature`, `scripts/lib/generated-feature.ts`)의 기능 하나로만 본다. - 새 context는 앱이 하나일 때만 만든다. 앱이 여럿이면 `--context`로 기존 context를 고른다. diff --git a/docs/work/new-feature.md b/docs/work/new-feature.md index 3d0124ba..ca06fcd3 100644 --- a/docs/work/new-feature.md +++ b/docs/work/new-feature.md @@ -56,7 +56,7 @@ - 생성 명령이 거부하면 `docs/manual/reference/errors.md`에서 메시지를 찾는다. 고칠 파일이 적혀 있다. - 짝 백엔드 응답 모양·오류 code가 문서와 다르면 코드(백엔드 생성기, 이 repo의 `src/adapters/http/backend-envelope.ts`)까지 따라가 사실을 적고 묻는다. 문서만 보고 판정 표를 정하지 않는다. - 기능 폴더 밖을 고쳐야만 되면 거기서 멈추고 [README](README.md) 5절 형식으로 묻는다. -- brief가 매뉴얼 예시 이름(`invoice-feature` 등)을 기능 ID로 주면 그대로 만들지 말고 묻는다. 템플릿 시험(`tests/unit/manual-code-blocks.test.ts`)이 저장소 사본에 그 이름으로 기능을 만든다. +- brief가 기능 ID를 `typecheck-probe-`로 시작하게 주면 그대로 만들지 말고 묻는다. 템플릿 시험이 저장소 사본에 만드는 예약 이름이다(`scripts/lib/template-probe-features.ts`). 매뉴얼 예시 이름(`invoice-feature`)은 써도 된다. ## 8. 보고 형식 diff --git a/docs/work/reference/defect-patterns.md b/docs/work/reference/defect-patterns.md index c36d9002..9b132814 100644 --- a/docs/work/reference/defect-patterns.md +++ b/docs/work/reference/defect-patterns.md @@ -37,7 +37,7 @@ | T4 | 브라우저의 추정에 기댄다 | WebKit이 load 3초 뒤 한 번 하는 preload 추정에 기대 곧 쓰일 preload로 실패하고, 정말 안 쓴 preload는 놓친다 | 1103/11-09 | 추정 대신 확인하려는 사실을 직접 검사한다(`testing.md` 5절) | 10, 21 | | T5 | 그리는 중인 화면을 누른다 | 앱 뒤에 붙인 버튼이 렌더링 중 밀려 클릭이 닿지 않는다 | 1103/11-10 | 테스트가 붙이는 조작 요소는 고정 층에(`testing.md` 5절) | 10, 21 | | T6 | 테스트 대역이 실제 상대와 다르다 | 메모리 IndexedDB, fake, 백엔드 문서에서 옮긴 MSW 응답이 실제와 달라 결함을 숨긴다 | 0925/05-08, 0925/06-01, 1103/05-04, 1103/16-01, 1105/01-01 | 실제 짝 백엔드 응답으로 맞추기는 미조치(1105 README 9절) | 10, 17, 12 | -| T7 | 플랫폼 테스트가 샘플·특정 파일·예시 이름에 묶인다 | 샘플을 지우면 테스트가 같이 사라지거나 게이트가 깨진다. 템플릿 테스트의 글자가 매뉴얼 예시 기능 이름과 부딪힌다 | 0925/14-01, 0929/10-02, 1101/16-02, 1105/10-01, 1105/16-04 | 테스트 전용 라우트와 플랫폼 소유 MSW 카탈로그(`testing.md` 2절). 탐침 이름은 예약 접두어 `typecheck-probe-*` | 27, 10, 21, 20 | +| T7 | 플랫폼 테스트가 샘플·특정 파일·예시 이름에 묶인다 | 샘플을 지우면 테스트가 같이 사라지거나 게이트가 깨진다. 템플릿 테스트의 글자가 매뉴얼 예시 기능 이름과 부딪힌다 | 0925/14-01, 0929/10-02, 1101/16-02, 1105/10-01, 1105/16-04, 1112/08-02 | 테스트 전용 라우트와 플랫폼 소유 MSW 카탈로그(`testing.md` 2절). 템플릿 시험이 사본에 만드는 기능·탐침 이름은 예약 접두어 `typecheck-probe-*` | 27, 10, 21, 20 | | T8 | 빠른 계층에 느린 테스트가 섞인다 | unit에 프로세스를 띄우는 도구 테스트, 실제 시계로 기다리는 테스트가 섞이고 같은 파일을 두 번 돈다 | 1101/10-05, 1101/10-06, 1101/10-07, 1101/15-04 | 없음. `testing.md` 6절 | 14, 20, 10 | | T9 | 깨끗한 clone·다른 호스트에서 실패한다 | gitignore된 생성물, 기준선을 만든 CPU, 실행기가 넣는 npm 환경변수에 기댄다 | 0924 6.0절, 0925/10-01, 0925/11-03, 1101/15-05 | 한 파일 실행도 `scripts/run-vitest.ts`로. merge 판정은 깨끗한 checkout에서(`gates.md` 2·3절) | 10, 21, 20 | | T10 | 지우거나 바꾼 코드가 지키던 검사·테스트를 같이 잃는다 | 삭제·이름 변경이 실행 동작만 옮기고, 지운 행·테스트가 지키던 규칙은 옮기지 않는다 | 1103/07-01, 1103/10-04, 1105/04-01, 1105/10-01 | `structure.md` 9절 | 10, 21, 17 | diff --git a/docs/work/reference/testing.md b/docs/work/reference/testing.md index 3dcff9a1..c2edeea8 100644 --- a/docs/work/reference/testing.md +++ b/docs/work/reference/testing.md @@ -39,7 +39,7 @@ - 스크립트 테스트가 자식 프로세스를 띄우면 그 suite가 자기 timeout을 선언한다. 전역 timeout을 올리지 않는다. - 값은 desktop에서 잰 가장 긴 실행으로 정한다: `childProcessTimeout()`(`tests/helpers/child-process-timeout.ts`). 부하가 높은 desktop에서 자식 프로세스 테스트가 평소보다 몇 배 느려진 실측을 근거로 둔다. - 기본 timeout인 테스트가 자식 프로세스를 띄우면 `tests/setup.ts`가 그 호출에서 실패시킨다. helper나 import한 스크립트가 띄워도 같다. hook(`beforeAll` 등)은 보지 않는다. -- 플랫폼을 지키는 테스트는 기능·스타터 화면에 묶지 않는다. 테스트 전용 라우트와 플랫폼 소유 MSW 카탈로그(`tests/mocks/`)를 쓴다(결함 패턴 T7). 생성물 탐침 이름은 예약 접두어(`typecheck-probe-*`)를 쓴다. +- 플랫폼을 지키는 테스트는 기능·스타터 화면에 묶지 않는다. 테스트 전용 라우트와 플랫폼 소유 MSW 카탈로그(`tests/mocks/`)를 쓴다(결함 패턴 T7). 템플릿 시험이 저장소 사본에 만드는 기능과 생성물 탐침의 이름은 예약 접두어(`typecheck-probe-*`, `scripts/lib/template-probe-features.ts`)를 쓴다. 사본에는 제품 기능이 들어 있어, 흔한 업무 이름이나 매뉴얼 예시 이름을 쓰면 그 이름의 기능을 만든 제품에서 생성 명령이 거부한다. - 기능 테스트가 지워도 되는 문서를 읽으면 제거 드릴이 깨진다([structure.md](structure.md) 4절). - 테스트 작성의 편집 직후 규칙은 `.claude/rules/tests.md`다(Claude Code는 테스트 파일을 열 때 읽는다). diff --git a/scripts/create-feature.ts b/scripts/create-feature.ts index 63b02aac..c05d60a0 100644 --- a/scripts/create-feature.ts +++ b/scripts/create-feature.ts @@ -139,7 +139,7 @@ function baseOf(id: string): string { : id; } -function namesOf(id: string) { +export function namesOf(id: string) { const base = baseOf(id); const pascal = base .split("-") diff --git a/scripts/lib/generated-feature.ts b/scripts/lib/generated-feature.ts index 8430f836..02cec085 100644 --- a/scripts/lib/generated-feature.ts +++ b/scripts/lib/generated-feature.ts @@ -5,9 +5,11 @@ import { tmpdir } from "node:os"; import path from "node:path"; import { pathToFileURL } from "node:url"; +import { namesOf } from "../create-feature.ts"; import { localBuildEnvironment } from "./build-environment.ts"; import { linkFixtureNodeModules } from "./fixture-node-modules.ts"; import { REMOVAL_FIXTURE_COPY_TARGETS } from "./removal-fixture.ts"; +import { TEMPLATE_PROBE_PREFIX } from "./template-probe-features.ts"; /** * 2026-11-07. The template ships no feature. What needs one in a real build @@ -19,8 +21,19 @@ import { REMOVAL_FIXTURE_COPY_TARGETS } from "./removal-fixture.ts"; * (scripts/scale/browser-soak.ts, `buildWithGeneratedFeature`). A change of * the generator's output fails there. The `--keyed` write slice is the widest * one the command makes. + * + * 1112/08-02. The id begins with the reserved probe prefix: the copy holds + * the product's own features, and a product that had built `order-feature` + * made create:feature refuse this one. */ -export const GENERATED_FEATURE_ID = "order-feature"; +export const GENERATED_FEATURE_ID = `${TEMPLATE_PROBE_PREFIX}order-feature`; + +const NAMES = namesOf(GENERATED_FEATURE_ID); + +/** The key of one of the feature's words (`.list.title`). */ +export function generatedMessageKey(suffix: string): string { + return `${NAMES.camel}.${suffix}`; +} export type GeneratedRoute = Readonly<{ routeId: string; @@ -48,7 +61,7 @@ function node(root: string, args: readonly string[]): string { return result.stdout; } -/** The edit of a fixture build: `corepack pnpm create:feature order-feature --with-create --keyed`. */ +/** The edit of a fixture build: `corepack pnpm create:feature --with-create --keyed`. */ export async function addGeneratedFeature(root: string): Promise { node(root, ["scripts/generate-product-feature-index.ts"]); node(root, ["scripts/create-feature.ts", GENERATED_FEATURE_ID, "--with-create", "--keyed"]); @@ -62,23 +75,24 @@ export async function addGeneratedFeature(root: string): Promise { export function generatedFeature(root: string): GeneratedFeature { const feature = path.join(root, "src/features", GENERATED_FEATURE_ID); const module = (file: string) => JSON.stringify(pathToFileURL(path.join(feature, file)).href); + const { base, upper } = NAMES; const source = ` - const { ORDER_FEATURE_CONTRACT } = await import(${module("contracts/order-feature-contract.ts")}); - const { ORDER_MESSAGE_CATALOGS } = await import(${module("contracts/order-message-catalog.ts")}); - const { ORDER_LIST_ITEMS_CONTRACT } = await import(${module("contracts/order-contract-contribution.ts")}); + const { ${upper}_FEATURE_CONTRACT: CONTRACT } = await import(${module(`contracts/${GENERATED_FEATURE_ID}-contract.ts`)}); + const { ${upper}_MESSAGE_CATALOGS: CATALOGS } = await import(${module(`contracts/${base}-message-catalog.ts`)}); + const { ${upper}_LIST_ITEMS_CONTRACT: LIST_ITEMS } = await import(${module(`contracts/${base}-contract-contribution.ts`)}); const { API_BASE_URL } = JSON.parse(await (await import("node:fs/promises")).readFile("config/runtime/local.json", "utf8")); const route = (id) => ({ routeId: id, - path: ORDER_FEATURE_CONTRACT.routes[id].path, - chunkId: ORDER_FEATURE_CONTRACT.routes[id].chunkId, - moduleId: ORDER_FEATURE_CONTRACT.routeRuntimeContracts[id].moduleId, + path: CONTRACT.routes[id].path, + chunkId: CONTRACT.routes[id].chunkId, + moduleId: CONTRACT.routeRuntimeContracts[id].moduleId, }); process.stdout.write(JSON.stringify({ - list: route("ORDER_LIST"), - detail: route("ORDER_DETAIL"), - create: route("ORDER_CREATE"), - messages: ORDER_MESSAGE_CATALOGS, - api: new URL(ORDER_LIST_ITEMS_CONTRACT.contract.pathTemplate.slice(1), API_BASE_URL).href, + list: route("${upper}_LIST"), + detail: route("${upper}_DETAIL"), + create: route("${upper}_CREATE"), + messages: CATALOGS, + api: new URL(LIST_ITEMS.contract.pathTemplate.slice(1), API_BASE_URL).href, })); `; return JSON.parse(node(root, ["--input-type=module", "-e", source])) as GeneratedFeature; diff --git a/scripts/lib/template-probe-features.ts b/scripts/lib/template-probe-features.ts new file mode 100644 index 00000000..027a7f61 --- /dev/null +++ b/scripts/lib/template-probe-features.ts @@ -0,0 +1,49 @@ +import { namesOf } from "../create-feature.ts"; + +/** + * 1112/08-02. Feature ids the template's own tests and drills create in a + * copy of the repository. The copy holds the product's features, and + * create:feature refuses an id a feature there already has, or one with the + * same prefix. A template test that used the manual's example + * (`invoice-feature`) or a plain business word (`order-feature`) therefore + * failed FE-GATE-005 and FE-GATE-008 in every product that had built a + * feature by that name. Each id here begins with the prefix the template + * reserves for its probes; docs/manual/reference/create-feature.md tells a + * product not to use it. + */ +export const TEMPLATE_PROBE_PREFIX = "typecheck-probe-"; + +/** The feature the manual's code blocks are written for (docs/manual/01-add-a-feature.md). */ +export const MANUAL_EXAMPLE_FEATURE_ID = "invoice-feature"; +/** What tests/unit/manual-code-blocks.test.ts creates and renames the blocks to. */ +export const MANUAL_PROBE_FEATURE_ID = `${TEMPLATE_PROBE_PREFIX}${MANUAL_EXAMPLE_FEATURE_ID}`; +/** The sample tests/unit/template-feature-removal-documents.test.ts lists and deletes. */ +export const LISTED_SAMPLE_PROBE_FEATURE_ID = `${TEMPLATE_PROBE_PREFIX}listed-sample-feature`; +/** What FE-GATE-020's scaffold drill (scripts/test-feature-scaffold.ts, test:sample-removal) creates. */ +export const SCAFFOLD_PROBE_FEATURE_ID = `${TEMPLATE_PROBE_PREFIX}scaffold-feature`; +/** The scaffold drill's `--with-create --keyed` feature. */ +export const SCAFFOLD_WRITE_PROBE_FEATURE_ID = `${TEMPLATE_PROBE_PREFIX}scaffold-write-feature`; + +function escape(text: string): string { + return text.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&"); +} + +/** + * `text` written for feature `fromId`, with every spelling create:feature + * derives from an id (`INVOICE_`, `Invoice`, `invoice-`, `invoice`) moved to + * the spelling it derives from `toId`. Prose that uses the word moves too; + * what matters is that the names a block defines and the names it imports + * from the generated feature move together. + */ +export function renameFeatureText(text: string, fromId: string, toId: string): string { + const from = namesOf(fromId); + const to = namesOf(toId); + const spellings = new Map([ + [from.upper, to.upper], + [from.pascal, to.pascal], + [`${from.base}-`, `${to.base}-`], + [from.camel, to.camel], + ]); + const pattern = new RegExp([...spellings.keys()].map(escape).join("|"), "gu"); + return text.replace(pattern, (match) => spellings.get(match) ?? match); +} diff --git a/scripts/test-feature-scaffold.ts b/scripts/test-feature-scaffold.ts index 77dd67f7..8a1539b8 100644 --- a/scripts/test-feature-scaffold.ts +++ b/scripts/test-feature-scaffold.ts @@ -4,6 +4,10 @@ import { mkdir, rm, writeFile } from "node:fs/promises"; import path from "node:path"; import { loadCiGateContract } from "./contracts/ci-gates.ts"; +import { + SCAFFOLD_PROBE_FEATURE_ID, + SCAFFOLD_WRITE_PROBE_FEATURE_ID, +} from "./lib/template-probe-features.ts"; import { runScaffoldDrillCommand, scaffoldDrillCommands, @@ -37,9 +41,10 @@ import { * test:sample-removal repeats the generation after deleting the sample * (decision 4), which proves the command needs nothing from it. */ -const FEATURE_ID = "scaffold-feature"; +/** 1112/08-02. Reserved probe ids: the copy holds the product's own features. */ +const FEATURE_ID = SCAFFOLD_PROBE_FEATURE_ID; /** 1103/09-06. The `--with-create --keyed` slice, in its own context. */ -const WRITE_FEATURE_ID = "scaffold-write-feature"; +const WRITE_FEATURE_ID = SCAFFOLD_WRITE_PROBE_FEATURE_ID; const REPORT = "artifacts/tests/feature-scaffold.xml"; const pnpmCli = requireRemovalFixtureEnvironment("npm_execpath"); diff --git a/scripts/test-sample-removal.ts b/scripts/test-sample-removal.ts index e60d011d..87a0ade0 100644 --- a/scripts/test-sample-removal.ts +++ b/scripts/test-sample-removal.ts @@ -32,6 +32,7 @@ import { type RemovalCheck, } from "./lib/removal-fixture.ts"; import { REMOVABLE_TEMPLATE_FEATURES } from "./lib/removable-template-features.ts"; +import { SCAFFOLD_PROBE_FEATURE_ID } from "./lib/template-probe-features.ts"; /** * 09-07 (D-10). Removes one installed feature, `--feature=`, from a copy @@ -528,7 +529,7 @@ try { // 1103/09-06. With the write slice (NEVER), which needs nothing from // the sample either. const created = check("scaffold-create-feature", "create:feature", [ - "scaffold-feature", + SCAFFOLD_PROBE_FEATURE_ID, "--with-create", ]); checks.push(created); diff --git a/tests/e2e/generated-feature.spec.ts b/tests/e2e/generated-feature.spec.ts index f80d424f..d0fc977e 100644 --- a/tests/e2e/generated-feature.spec.ts +++ b/tests/e2e/generated-feature.spec.ts @@ -11,6 +11,7 @@ import { import { addGeneratedFeature, generatedFeature, + generatedMessageKey, routePath, type GeneratedFeature, } from "../../scripts/lib/generated-feature.ts"; @@ -122,10 +123,10 @@ async function signInAt(page: Page, path: string, heading: string) { await expect(page.getByRole("heading", { level: 1 })).toHaveText(heading); } -const openForm = (page: Page) => signInAt(page, routePath(feature.create), word("order.form.title")); +const openForm = (page: Page) => signInAt(page, routePath(feature.create), word(generatedMessageKey("form.title"))); const nameField = (page: Page) => - page.getByRole("textbox", { name: new RegExp(word("order.form.name"), "u") }); -const saveButton = (page: Page) => page.getByRole("button", { name: word("order.form.save") }); + page.getByRole("textbox", { name: new RegExp(word(generatedMessageKey("form.name")), "u") }); +const saveButton = (page: Page) => page.getByRole("button", { name: word(generatedMessageKey("form.save")) }); async function expectNoBlockingViolations(page: Page) { const results = await new AxeBuilder({ page }).withTags(WCAG_TAGS).analyze(); @@ -154,7 +155,7 @@ async function saveFromKeyboard(page: Page, firstAction: string) { test.describe("the route", () => { test("opens the protected list through the local demo sign-in", async ({ page }) => { await answerReads(page); - await signInAt(page, routePath(feature.list), word("order.list.title")); + await signInAt(page, routePath(feature.list), word(generatedMessageKey("list.title"))); // The closed menu drawer holds a second copy of the status (08-01). await expect( @@ -167,16 +168,16 @@ test.describe("the route", () => { // 08-04. Feature screens take their words from the catalog. test("draws its screens without Korean copy in en-US", async ({ page }) => { await answerReads(page); - await signInAt(page, routePath(feature.list), word("order.list.title")); + await signInAt(page, routePath(feature.list), word(generatedMessageKey("list.title"))); await page.getByRole("combobox", { name: "언어" }).first().selectOption("en-US"); const main = page.getByRole("main"); const english = feature.messages["en-US"]; - await expect(main.getByRole("heading", { level: 1 })).toHaveText(english["order.list.title"]!); + await expect(main.getByRole("heading", { level: 1 })).toHaveText(english[generatedMessageKey("list.title")]!); await expect(main).not.toContainText(/[가-힣]/u); - await main.getByRole("link", { name: english["order.list.create"]! }).click(); - await expect(main.getByRole("button", { name: english["order.form.save"]! })).toBeVisible(); + await main.getByRole("link", { name: english[generatedMessageKey("list.create")]! }).click(); + await expect(main.getByRole("button", { name: english[generatedMessageKey("form.save")]! })).toBeVisible(); await expect(main).not.toContainText(/[가-힣]/u); }); }); @@ -196,7 +197,7 @@ test.describe("the form", () => { await nameField(page).fill("Unsaved order"); await page .getByRole("navigation", { name: KO_MESSAGES["template.breadcrumb"] }) - .getByRole("link", { name: word("order.list.title") }) + .getByRole("link", { name: word(generatedMessageKey("list.title")) }) .click(); const dialog = page.getByRole("dialog", { name: KO_MESSAGES["form.unsaved.title"] }); @@ -331,7 +332,7 @@ test.describe("the save", () => { await page.keyboard.press("Enter"); - await expect(page.getByRole("heading", { level: 1 })).toHaveText(word("order.list.title")); + await expect(page.getByRole("heading", { level: 1 })).toHaveText(word(generatedMessageKey("list.title"))); await expect(page.getByRole("link", { name: ITEM.name })).toBeVisible(); expect(calls).toHaveLength(1); }); @@ -350,7 +351,7 @@ test.describe("accessibility", () => { ] as const) { test(`@a11y list ${state} state has no blocking violations`, async ({ page }) => { await answerReads(page, list); - await signInAt(page, routePath(feature.list), word("order.list.title")); + await signInAt(page, routePath(feature.list), word(generatedMessageKey("list.title"))); await expect(page.getByRole("main")).toContainText(visible); await expectNoBlockingViolations(page); }); diff --git a/tests/unit/manual-code-blocks.test.ts b/tests/unit/manual-code-blocks.test.ts index 43cf272e..c0182600 100644 --- a/tests/unit/manual-code-blocks.test.ts +++ b/tests/unit/manual-code-blocks.test.ts @@ -9,6 +9,11 @@ import { afterAll, describe, expect, it } from "vitest"; import { linkFixtureNodeModules } from "../../scripts/lib/fixture-node-modules.ts"; import { REMOVAL_FIXTURE_COPY_TARGETS } from "../../scripts/lib/removal-fixture.ts"; import { selectRepositoryPaths } from "../../scripts/lib/repository-layout.ts"; +import { + MANUAL_EXAMPLE_FEATURE_ID, + MANUAL_PROBE_FEATURE_ID, + renameFeatureText, +} from "../../scripts/lib/template-probe-features.ts"; /** * 2026-11-07. The template ships no sample feature: what the generated @@ -19,9 +24,15 @@ import { selectRepositoryPaths } from "../../scripts/lib/repository-layout.ts"; * block goes to its path unchanged, and the app and test typecheck programs, * lint and the feature's tests run on it. A block that is a test runs as it * is; what the other blocks do is checked by tests/fixtures/manual-code-blocks. + * + * 1112/08-02. The copy holds the product's own features, and a product may + * well have built `invoice-feature`. So the copy gets the reserved probe + * feature instead, and every block and check is renamed to it on the way in + * (`renameFeatureText`): paths, constants, types and words alike. */ const MANUAL = "docs/manual"; -const FEATURE_ID = "invoice-feature"; +const FEATURE_ID = MANUAL_PROBE_FEATURE_ID; +const toProbe = (text: string) => renameFeatureText(text, MANUAL_EXAMPLE_FEATURE_ID, FEATURE_ID); const CHECKS = "tests/fixtures/manual-code-blocks"; const MARKED_BLOCK = /\n```tsx?\n([\s\S]*?)\n```/gu; @@ -100,18 +111,18 @@ describe("docs/manual code blocks, pasted into a generated feature", () => { expect(created.status, created.output).toBe(0); for (const [target, block] of blocks) { - const file = path.join(root, target); + const file = path.join(root, toProbe(target)); // A block adds a file; it never stands in for one the command wrote. expect(existsSync(file), `${target} exists before the block is pasted`).toBe(false); await mkdir(path.dirname(file), { recursive: true }); - await writeFile(file, block); + await writeFile(file, toProbe(block)); } const checks = (await readdir(CHECKS)).filter((name) => name.endsWith(".check.tsx")); expect(checks.length).toBeGreaterThan(0); for (const check of checks) { await writeFile( path.join(root, "tests/features", FEATURE_ID, check.replace(/\.check\.tsx$/u, ".test.tsx")), - (await readFile(path.join(CHECKS, check), "utf8")).replaceAll("{{feature}}", FEATURE_ID), + toProbe((await readFile(path.join(CHECKS, check), "utf8")).replaceAll("{{feature}}", MANUAL_EXAMPLE_FEATURE_ID)), ); } diff --git a/tests/unit/template-feature-removal-documents.test.ts b/tests/unit/template-feature-removal-documents.test.ts index 97871646..2a1b7332 100644 --- a/tests/unit/template-feature-removal-documents.test.ts +++ b/tests/unit/template-feature-removal-documents.test.ts @@ -16,6 +16,7 @@ import { REMOVAL_FIXTURE_DOCUMENT_TARGETS, } from "../../scripts/lib/removal-fixture.ts"; import { selectRepositoryPaths } from "../../scripts/lib/repository-layout.ts"; +import { LISTED_SAMPLE_PROBE_FEATURE_ID } from "../../scripts/lib/template-probe-features.ts"; /** * 1105/14-01. A copy that deleted a sample listed in @@ -23,15 +24,18 @@ import { selectRepositoryPaths } from "../../scripts/lib/repository-layout.ts"; * the FE-GATE-005 copy of it ("passes the documents as they are") wherever * the documents named the sample's folders. The template lists no sample * since 2026-11-07, so the copy here gets one: the feature `create:feature` - * writes, listed and named in a document, then deleted. + * writes, listed and named in a document, then deleted. Its id begins with + * the reserved probe prefix, so a product's own features never clash with it + * (1112/08-02). */ const CHECKER = "scripts/verify-documentation-readiness.ts"; /** What verify:documentation reads besides the code: the documents a drill copies. */ const DOCUMENTS = REMOVAL_FIXTURE_DOCUMENT_TARGETS; +const LISTED_SAMPLE_BASE = LISTED_SAMPLE_PROBE_FEATURE_ID.replace(/-feature$/u, ""); const LISTED_SAMPLE = Object.freeze({ - featureId: "listed-sample-feature", - contextDirectory: "src/contexts/listed-sample-context", + featureId: LISTED_SAMPLE_PROBE_FEATURE_ID, + contextDirectory: `src/contexts/${LISTED_SAMPLE_BASE}-context`, extraPaths: Object.freeze([]), scripts: Object.freeze([]), }); @@ -87,7 +91,8 @@ async function copyWithListedSample() { for (const entry of removableTemplateFeaturePaths(LISTED_SAMPLE)) { await rm(path.join(root, entry), { recursive: true, force: true }); } - await rm(path.join(root, "docs/accessibility/route-reviews/LISTED_SAMPLE_LIST.md"), { force: true }); + const listRoute = `${LISTED_SAMPLE_BASE.toUpperCase().replaceAll("-", "_")}_LIST`; + await rm(path.join(root, `docs/accessibility/route-reviews/${listRoute}.md`), { force: true }); expect(node(["scripts/generate-product-feature-index.ts"]).status).toBe(0); }, cleanUp: () => rm(parent, { recursive: true, force: true }), diff --git a/tests/unit/template-probe-features.test.ts b/tests/unit/template-probe-features.test.ts new file mode 100644 index 00000000..2afd684a --- /dev/null +++ b/tests/unit/template-probe-features.test.ts @@ -0,0 +1,109 @@ +import { describe, expect, it } from "vitest"; + +import { planFeature, type InstalledFacts } from "../../scripts/create-feature.ts"; +import { GENERATED_FEATURE_ID } from "../../scripts/lib/generated-feature.ts"; +import { + LISTED_SAMPLE_PROBE_FEATURE_ID, + MANUAL_EXAMPLE_FEATURE_ID, + MANUAL_PROBE_FEATURE_ID, + SCAFFOLD_PROBE_FEATURE_ID, + SCAFFOLD_WRITE_PROBE_FEATURE_ID, + TEMPLATE_PROBE_PREFIX, + renameFeatureText, +} from "../../scripts/lib/template-probe-features.ts"; + +/** + * 1112/08-02. The template's own tests add a feature to a copy of the + * repository, and that copy holds the product's features. create:feature + * refuses an id a feature there has, or one with the same prefix, so a + * template test that used the manual's example (`invoice-feature`) or a plain + * business word (`order-feature`) failed FE-GATE-005 and FE-GATE-008 in a + * product that had built a feature by that name. + */ +const PROBE_IDS = Object.freeze([ + GENERATED_FEATURE_ID, + MANUAL_PROBE_FEATURE_ID, + LISTED_SAMPLE_PROBE_FEATURE_ID, + SCAFFOLD_PROBE_FEATURE_ID, + SCAFFOLD_WRITE_PROBE_FEATURE_ID, +]); + +const TOPIC_SUFFIX = "abcdefghjkmnpqrstvwxyz0123"; + +/** A product that built features by the names a business app would pick. */ +const PRODUCT: InstalledFacts = Object.freeze({ + appIds: ["template-app"], + featureIds: [ + "invoice-feature", + "order-feature", + "orders-feature", + "scaffold-feature", + "listed-sample-feature", + "invoice", + "order", + ], + contexts: [ + { id: "invoice-context", routePath: "invoices/*" }, + { id: "order-context", routePath: "orders/*" }, + ], + contextDirectories: ["invoice-context", "order-context"], + routes: [ + { routeId: "INVOICE_LIST", path: "/invoices", chunkId: "route-invoice-list", navigationOrder: 50 }, + { routeId: "ORDER_LIST", path: "/orders", chunkId: "route-order-list", navigationOrder: 60 }, + ], + topics: [], + messageKeys: ["invoice.list.title", "order.list.title"], +}); + +/** The template as it ships: no feature. */ +const TEMPLATE: InstalledFacts = Object.freeze({ + appIds: ["template-app"], + featureIds: [], + contexts: [], + contextDirectories: [], + routes: [], + topics: [], + messageKeys: [], +}); + +describe("feature ids the template's tests create in a copy", () => { + it("all begin with the reserved probe prefix", () => { + for (const id of PROBE_IDS) expect(id.startsWith(TEMPLATE_PROBE_PREFIX), id).toBe(true); + expect(new Set(PROBE_IDS).size).toBe(PROBE_IDS.length); + }); + + it("are accepted in a product that built features by business names", () => { + for (const id of PROBE_IDS) { + expect(() => planFeature({ id, write: "KEYED" }, PRODUCT, () => TOPIC_SUFFIX), id).not.toThrow(); + } + }); +}); + +describe("renameFeatureText", () => { + it("moves every spelling of the manual's example to the probe's", () => { + const text = [ + "src/features/invoice-feature/presentation/use-invoice-list-filters.ts", + "INVOICE_LIST INVOICE_CREATE_EFFECT InvoiceProblem useInvoiceListFilters", + "invoiceListSearchSchema invoice.list.title /invoices invoice-create-v1", + ].join("\n"); + + expect(renameFeatureText(text, MANUAL_EXAMPLE_FEATURE_ID, MANUAL_PROBE_FEATURE_ID)).toBe( + [ + "src/features/typecheck-probe-invoice-feature/presentation/use-typecheck-probe-invoice-list-filters.ts", + "TYPECHECK_PROBE_INVOICE_LIST TYPECHECK_PROBE_INVOICE_CREATE_EFFECT TypecheckProbeInvoiceProblem useTypecheckProbeInvoiceListFilters", + "typecheckProbeInvoiceListSearchSchema typecheckProbeInvoice.list.title /typecheckProbeInvoices typecheck-probe-invoice-create-v1", + ].join("\n"), + ); + }); + + it("gives the names create:feature writes for the probe", () => { + const manual = planFeature({ id: MANUAL_EXAMPLE_FEATURE_ID, write: "NEVER" }, TEMPLATE, () => TOPIC_SUFFIX); + const probe = planFeature({ id: MANUAL_PROBE_FEATURE_ID, write: "NEVER" }, TEMPLATE, () => TOPIC_SUFFIX); + + expect( + [...manual.files.keys()].map((file) => + renameFeatureText(file, MANUAL_EXAMPLE_FEATURE_ID, MANUAL_PROBE_FEATURE_ID), + ), + ).toEqual([...probe.files.keys()]); + }); +}); -- 2.54.0 From e1986be659ca53e93d5bc178ceae265ae52850ab Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 12 Nov 2026 22:31:34 +0900 Subject: [PATCH 02/28] =?UTF-8?q?docs(reviews):=20round9=20=ED=99=95?= =?UTF-8?q?=EC=9D=B8=20=EB=A6=AC=EB=B7=B0=20=EA=B2=B0=EA=B3=BC=EB=A5=BC=20?= =?UTF-8?q?=EC=A0=81=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit main 5250ff95 전체를 분야 렌즈 아홉(React, 구조·공통 계약, 시험·QA, UX·디자인 시스템, 접근성, 성능·빌드, 보안, 가드레일·문서, 나머지 adapter)과 지난 발견 재판정 둘로 나눠 리뷰했다. 새 발견은 반박 검증을 거쳐 80건이다(High 0, P1 1: 1112/08-02 템플릿 시험의 고정 기능 ID). 지난 리뷰가 연 118행은 고쳐짐 33, 일부 35, 남음 46, 재발 2다. 리뷰 README 하나와 영역 기록 열다섯을 docs/reviews/2026-11-round9-*.md 파일 묶음으로 둔다. 영역 기록은 서브에이전트가 쓴 원문이고, 작업 폴더 절대 경로만 줄였다. 리뷰 중 코드는 고치지 않았다. 위험·한계: 실행 증거는 desktop에 CI env를 준 실행이다(실제 runner 미검증). 실험 X-GD02·X-GD02b와 수정 라운드는 README 16절에 이어 적는다. 결정이 필요한 12건(R9-D1~D12)은 권하는 안과 함께 7절에 있다. 검증: scripts/verify.sh docs(노트북) 통과. 게이트 실행 결과는 README 11.1절(merge 13/14 rc=0, FE-GATE-013은 호스트 제약 조건 충족, documentation rc=0). Refs: round9 확인 리뷰 --- docs/ledger/estimates.jsonl | 1 + docs/reviews/2026-11-round9-01-react.md | 330 +++++++++++ .../2026-11-round9-02-structure-contracts.md | 243 ++++++++ docs/reviews/2026-11-round9-03-testing-qa.md | 232 ++++++++ .../2026-11-round9-04-ux-design-system.md | 435 ++++++++++++++ .../2026-11-round9-05-accessibility.md | 460 +++++++++++++++ .../2026-11-round9-06-performance-build.md | 342 +++++++++++ docs/reviews/2026-11-round9-07-security.md | 205 +++++++ .../2026-11-round9-08-guardrails-docs.md | 392 +++++++++++++ docs/reviews/2026-11-round9-09-adapters.md | 269 +++++++++ .../2026-11-round9-10-prior-findings-a.md | 267 +++++++++ .../2026-11-round9-11-prior-findings-b.md | 533 ++++++++++++++++++ ...ound9-12-verify-react-adapters-security.md | 45 ++ ...1-round9-13-verify-structure-guardrails.md | 63 +++ ...11-round9-14-verify-testing-performance.md | 52 ++ .../2026-11-round9-15-verify-ux-ds-a11y.md | 105 ++++ docs/reviews/2026-11-round9-review.md | 358 ++++++++++++ 17 files changed, 4332 insertions(+) create mode 100644 docs/reviews/2026-11-round9-01-react.md create mode 100644 docs/reviews/2026-11-round9-02-structure-contracts.md create mode 100644 docs/reviews/2026-11-round9-03-testing-qa.md create mode 100644 docs/reviews/2026-11-round9-04-ux-design-system.md create mode 100644 docs/reviews/2026-11-round9-05-accessibility.md create mode 100644 docs/reviews/2026-11-round9-06-performance-build.md create mode 100644 docs/reviews/2026-11-round9-07-security.md create mode 100644 docs/reviews/2026-11-round9-08-guardrails-docs.md create mode 100644 docs/reviews/2026-11-round9-09-adapters.md create mode 100644 docs/reviews/2026-11-round9-10-prior-findings-a.md create mode 100644 docs/reviews/2026-11-round9-11-prior-findings-b.md create mode 100644 docs/reviews/2026-11-round9-12-verify-react-adapters-security.md create mode 100644 docs/reviews/2026-11-round9-13-verify-structure-guardrails.md create mode 100644 docs/reviews/2026-11-round9-14-verify-testing-performance.md create mode 100644 docs/reviews/2026-11-round9-15-verify-ux-ds-a11y.md create mode 100644 docs/reviews/2026-11-round9-review.md diff --git a/docs/ledger/estimates.jsonl b/docs/ledger/estimates.jsonl index 23a0baa9..05a2478f 100644 --- a/docs/ledger/estimates.jsonl +++ b/docs/ledger/estimates.jsonl @@ -1,3 +1,4 @@ {"schema": 1, "kind": "estimate", "task": "fe-c-harness", "recorded_at": "2026-11-08T16:55+09:00", "transcript": "710988b0-b66b-4749-9bee-e0a2de8282e3", "started_at": "2026-11-08T16:47:38+09:00", "base": "ad3a071f", "task_kind": "docs-writing+improve", "size": "large", "minutes": {"p30": 80, "p50": 115, "p80": 170}, "calls": {"p30": 180, "p50": 260, "p80": 380}, "output_tokens": {"p30": 250000, "p50": 350000, "p80": 500000}, "basis": "착수 노트(공유 노트 fe-c-harness.md, 16:55)에 쓴 값을 옮겼다. 선례 h3-backend-harness 작업 중 68분·호출 270·출력 34.6만(손 판단 결정 약 25, desktop 실행 3회). 이번 결정 약 22(훅 언어와 범위, verify.sh 운반부, 템플릿 계약 분류, PR #6 11개를 playbook 6개와 reference로 나누기, 테스트 영향 셋)와 새로 쓰는 문서가 h3보다 많다(약 1,500줄 출력). desktop은 merge 단계 1~2회(한 번 약 25분, 잠금 대기는 시간에서 뺌). h3의 교훈대로 파일 수가 아니라 결정 수와 desktop 실행 횟수로 잡았다"} {"schema": 1, "kind": "actual", "task": "fe-c-harness", "recorded_at": "2026-11-08T22:41+09:00", "transcript": "710988b0-b66b-4749-9bee-e0a2de8282e3", "minutes": 352, "active_minutes": 124, "calls": 247, "output_tokens": 347752, "cache_read_tokens": 134943937, "max_context": 844410, "within": "p80", "result": "done", "commits": ["3524d6b0", "6e8cc963", "9f859628", "9961ecb1", "c6e42528", "9d65a41d", "98f5c6e7", "7b565ea0", "8721be47", "4a21bc79", "c50da347", "18ea5e93", "8faec86d"], "why": "시간은 p50을 넘고 p80 안이다. 예측 근거(결정 약 22, 문서 약 1,500줄)는 맞았지만 셋이 더 들었다: 처음 읽는 서브에이전트 시험이 찾은 빈틈 21개를 고치는 일(약 25분, verify.sh 인자 전달·돌려받기 포함), 노트북에서 못 돌리는 node 시험의 결함을 desktop merge 단계에서야 찾아 다시 돌린 일, 공유 잠금 대기 중 네트워크가 끊겨 돌던 실행 셋을 다시 돌린 일. 벽시계 352분의 대부분은 잠금 대기와 네트워크 단절이다. 다음 예측은 desktop 실행 횟수에 '노트북에서 못 보는 검사의 재실행 1회'를 기본으로 넣는다. 실측은 22:40까지의 세션 기록이고 뒤의 보고는 들어 있지 않다"} {"schema": 1, "kind": "actual", "task": "fe-c-harness", "recorded_at": "2026-11-09T00:50+09:00", "correction": true, "transcript": "710988b0-b66b-4749-9bee-e0a2de8282e3", "minutes": 482, "active_minutes": 192, "calls": 310, "output_tokens": 404844, "cache_read_tokens": 191539759, "max_context": 943733, "within": "over", "result": "done", "commits": ["93e3c7b1", "f117a5af", "48dc9f5b", "23df3203", "5fab0e46"], "why": "22:40 줄을 고친다. 그 뒤 총괄 대조로 계층 폴더 AGENTS.md 9개와 비전·문제 정의 양식이 범위에 더해졌다(약 45분). 새 트리 게이트가 INVENTORY 합계 줄과 parts의 SOURCE_DATE_EPOCH로 한 번 더 실패해 다시 돌렸다. 예측 근거에 없던 범위 추가와 desktop 재실행 둘이 p80을 넘긴 이유다. 다음 예측은 총괄 대조 뒤 추가 범위를 위해 p80에 한 묶음을 더 둔다"} +{"schema": 1, "kind": "estimate", "task": "r9-fe-review", "recorded_at": "2026-11-12T22:30+09:00", "transcript": "e654030f-a9e7-4a7d-912b-f0e8516c1147", "started_at": "2026-11-12T21:00+09:00", "base": "5250ff95", "task_kind": "improve", "size": "large", "minutes": {"p30": 300, "p50": 480, "p80": 840}, "calls": {"p30": 400, "p50": 650, "p80": 1000}, "output_tokens": {"p30": 300000, "p50": 500000, "p80": 800000}, "basis": "착수 노트(공유 노트 r9-fe-review.md)에 쓴 시간 예측을 옮겼다. 1회차 리뷰는 리뷰어 11개 병렬과 반박 검증 4개로 약 2시간(선례 1106 리뷰 16영역). 착수 때 수정 묶음을 2~6개로 봤으나 1회차 결과가 원인 묶음 14개(약 140건)라, 이 예측은 결정 대기 항목을 빼고 혼자 고치는 경우에 이미 모자랄 가능성이 크다. desktop 공유 잠금 대기(다른 세션과 겹쳐 15~45분)는 시간에서 뺐다"} diff --git a/docs/reviews/2026-11-round9-01-react.md b/docs/reviews/2026-11-round9-01-react.md new file mode 100644 index 00000000..69c08559 --- /dev/null +++ b/docs/reviews/2026-11-round9-01-react.md @@ -0,0 +1,330 @@ +# round9 L1 — fe-react 렌즈 + SRP (전체 리뷰) + +> round9 리뷰(2026-11-12, 대상 main `5250ff95`)의 영역 기록이다. 서브에이전트가 쓴 원문을 그대로 옮겼다. 바꾼 것은 이 인용 블록과, 작업 폴더 절대 경로를 `(작업 폴더)`로 줄인 것뿐이다. 발견 ID는 이 파일의 이름표(R-01 등)이고, 라운드 ID(`1112/NN-MM`)와의 대응은 [README](2026-11-round9-review.md) 15절이다. + + +대상: `5250ff95`(tree `75cc3752`). 읽기만 했다. repo 파일을 고치지 않았다. 실행은 하지 않았다(실험 요청 4절). + +## 0. 결론 + +- 판정: **고칠 것 있음.** 새 High 0, 새 P1 0. +- 발견 6건: Medium·P2 1(구조적 위험, SRP), Low·P3 5(확인된 결함 4, 구조적 위험 1). +- 결과 불명 쓰기의 재전송 입구(재전송 버튼, 같은 입력 재저장, 실행기 재시도, poll, 업로드)는 이번에 새로 열린 곳을 찾지 못했다. NEVER는 같은 입력을 `UNKNOWN_EFFECT_PENDING`으로 막고, KEYED는 같은 키를 쓰고, 1106/03-01 수정(재전송의 쓰기 전 거절은 결과 불명 유지)도 코드에 있다. +- 가장 큰 것은 R-01이다. 결과 불명 상태를 코디네이터와 폼이 따로 갖고, 둘을 맞추는 판정은 생성된 작성 페이지 사본에 있다. 플랫폼에서 고친 것(1105/08-02, 1105/08-04, 1106/08-02)이 이미 생성한 기능으로 전파되지 않는다. R-02는 그 구조에서 나온 증상이다. + +## 1. 범위 + +### 읽은 경로 + +- 바뀐 곳 먼저(`git diff --stat bbde570 5250ff95`): 참조 샘플 기능 3개 삭제(`reference-feature`, `platform-examples-feature`, `local-draft-feature`). 이제 기능 React 코드는 생성 명령 템플릿이 전부다. `application-query.ts`(1106/03-01·03-03 수정), `use-app-form.ts`(1106/03-01·08-01), `errors.ts`(`isRefusedOnEveryAttempt`), `backend-envelope.ts`·`fileserver-upload.ts`(traceId). +- `src/presentation/adapters/query/` 전 파일(7). +- `src/presentation/forms/` 전 파일(5), `src/presentation/pages/` 2. +- `src/adapters/query-cache/`: `server-state-scope-runtime.ts`, `tanstack-cache-coordinator.ts`, `tanstack-query-cache.ts` 전체, 나머지는 훑음(소비자 없는 확장 지점). +- `src/adapters/http/`: `backend-envelope.ts`·`feature-http-binding.ts`·`platform-error-mapping.ts` 전체, `http-execution-v3.ts`는 실행 루프·재시도 판정·결과 helper(517-1180, 1854-1934), `fileserver-upload.ts`는 재시도·effect 부분. +- `src/contracts/errors.ts` 전체, `server-state.ts`(bind·mutation 정책), `query-keys.ts`(identity registry), `diagnostics.ts`(`safeErrorKind`). +- `src/application/`: `view-models/async-state.ts`, `policies/bounded-polling.ts`, `create-application.ts`(일부). +- 경계: `src/presentation/components/async-surface.tsx`, `boundaries/render-error-boundary.tsx`, `chunk-recovery-boundary.tsx`, `routes/app-router.tsx`(경계 연결부), `routes/route-input.tsx`. +- 생성 템플릿: `scripts/create-feature.ts`(feature API, gateway, routes, `use--items`, 목록 페이지, 입력 테스트), `scripts/create-feature-write-slice.ts`(descriptor, gateway 조각, `use--item`, `use--create`, 폼, 상세·작성 페이지, 작성 페이지 테스트). +- 계약 문서: `docs/architecture/backend-api-and-server-state-contract.md` 4·4.1·4.2·6·6.1절, `docs/manual/02-decision-tables.md` 3·4절, `docs/manual/01-add-a-feature.md` 7·8단계, `src/{application,features,presentation,adapters,contracts}/AGENTS.md`, `docs/work/reference/{review-criteria,decisions,defect-patterns}.md`, 테스트 전략 설계 7.1·7.2절, CHANGELOG 196·287행. +- 짝 백엔드: `scripts/new-feature.sh` 이름 변환(앞 60행)만. 프론트 `namesOf`와 code 이름 규칙이 같음을 확인했다. + +### 쓴 스킬과 그 기준으로 본 것 + +- `fe-react` 함정 1(재전송 입구 다섯), 2(status+code 판정), 3(`commandMutationIdentity`), 4(서버 상태 위치), 5(TanStack 직접 import), 6(라우트 codec), 7(effect), 8(`REJECT_WHILE_ACTIVE`), 9(409·필드 문구), 10(오류 경계 reset), 12(브라우저 저장소). 체크리스트 「상태」(파생 값), 「데이터」(abort를 telemetry 실패로 세지 않음, 무효화 범위, rollback), 「렌더」(key, 정리). +- SRP: 한 모듈·hook·컴포넌트가 바뀌는 이유가 둘 이상인 곳, 같은 판정이 여러 곳에 있는 곳. R-01, R-06이 여기서 나왔다. + +### 확인 못 한 것 + +- 실행 없음. 모든 발견은 E1이다. 4절 실험으로 E2를 만든다. +- 게이트: desktop `/tmp/claude-gates/r9fe-base/summary.txt`를 읽었다. tree `75cc3752`(= `5250ff95`의 tree, 스냅샷 커밋 `b693d36f`)에서 FE-GATE-001~012 rc=0, FE-GATE-013 rc=1(결정 D8 대상인지 로그는 안 봤다), FE-GATE-020은 읽을 때 진행 중이었다. 이 결과는 발견들을 반박하지 않는다(발견마다 그 경로를 보는 테스트가 없음을 확인했다). +- 화면으로만 아는 것: R-02·R-05의 실제 화면 흐름. `verify-app`으로 열 곳은 `--with-create --keyed`로 만든 기능의 작성 라우트(저장 중 목록으로 갔다 돌아옴 → 이름 입력 → 「같은 요청으로 다시 보내기」), 목록 라우트(배경 재조회 실패 → 「다시 시도」 중 표시). +- `http-execution-v3.ts`의 `admitResponse`·`admitProblem`(1248-1800)은 지난 라운드들이 깊게 본 곳이라 훑기만 했다. + +## 2. 발견 + +### R-01 결과 불명 화면의 판정이 코디네이터·폼·생성 페이지 사본 세 곳에 나뉘어 있다 + +| 칸 | 내용 | +| --- | --- | +| 성격 | 구조적 위험 (SRP) | +| 관련 관점 | 3, 4, 5, 22, 23, 25 | +| 심각도·우선순위 | Medium·P2. 지금 템플릿 출력은 맞게 동작한다. 그러나 이 판정의 결함은 지난 두 라운드에 세 번 났고(1105/08-02, 1105/08-04, 1106/08-02), 고칠 때마다 이미 생성한 기능은 옛 판정을 그대로 갖는다. `--with-create`로 만든 모든 기능이 복제한다 | +| 통제 | M1 — CHANGELOG가 "이미 생성한 기능은 바뀌지 않는다. … `mounted` ref를 손으로 옮긴다"고 적는다(`CHANGELOG.md:196`). 옮겼는지 보는 검사는 없다. 생성 기능을 새 판정으로 올리는 절차 문서도 없다(`docs/manual`, `docs/work`, `docs/operations`에서 0건) | +| 증거 | E1 | +| 근거 | (1) 코디네이터가 결과 불명을 소유한다: 채널의 UNKNOWN admission(`src/presentation/adapters/query/application-query.ts:310-321`, `:623-633`). (2) 폼이 결과 불명을 따로 갖는다: `unknownSubmissionRef`와 `result: "effect-unknown"`(`src/presentation/forms/use-app-form.ts:114`, `:304-310`). 재전송 결과도 폼이 다시 판정한다: `resendLeftUnknown`(`use-app-form.ts:522-530`)은 코디네이터의 `resendLeavesUnknown`(`application-query.ts:643-646`)을 결과에서 거꾸로 추론한 사본이다. 둘은 이미 다르다: 폼은 `action === "reauth"`를 빼고(`:527`), 코디네이터는 `replayed`와 scope를 본다(`:644-645`). 401 재전송 뒤 코디네이터는 UNKNOWN을 쥐는데 폼은 `unknownSubmissionRef`를 비운다(`use-app-form.ts:297-303`). (3) 둘을 맞추는 규칙은 생성된 페이지 사본에 있다: `effectUnknown`·`blocked`·`otherSaveRunning`(`scripts/create-feature-write-slice.ts:674-679`), 저장 중 이탈 가드를 `!form.pending`으로 끔(`:680`), 마운트된 동안만 이동(`:639-656`), 확인 → `settleApplied` → 목록(`:736-741`), 재전송 → `openSaved`가 `applyOutcome`보다 먼저 이동(`:744`), feedback 고르기(`:724-750`). 폼이 진짜 상태를 모르니 페이지가 `mutation.state.indicator`로 막는다. `src/application/AGENTS.md`는 "결과 불명 쓰기의 재전송 판정은 한 곳에 둔다"고 적는다 | +| 발생 조건 | 플랫폼이 이 판정을 다시 고친다(지난 세 번처럼). 또는 제품이 생성 페이지를 손보면서 세 조각 중 하나를 빠뜨린다 | +| 영향 | 다운스트림 기능은 고쳐진 결함(예: 1106/08-02 저장이 떠난 사용자를 상세로 끌고 감)을 조용히 갖고 있다. 기능 수만큼 손 이식 비용이 든다. 폼과 코디네이터가 엇갈리는 상태(재마운트, 재인증)는 페이지가 매번 따로 맞춘다. R-02가 그 엇갈림에서 나온 결함이다 | +| 최소 개선 방향 | 결과 불명 상태의 소유자를 코디네이터 하나로 둔다. 폼은 코디네이터 상태를 읽는다(`useAppForm`에 mutation controller를 넘기거나, `src/presentation/forms/`에 `useMutationForm(mutation, formOptions)` 같은 platform hook을 둔다). 그 hook이 막기·피드백 고르기·마운트된 동안만 이동·확인·재전송 뒤 정리를 가진다. 생성 페이지는 그 hook과 필드·문구만 갖는다. 이미 생성한 기능의 이행 안내를 CHANGELOG [계약]에 한 번 적는다 | +| 완료 기준 | 생성된 `-create-page.tsx`에 `mutation.state.indicator` 비교, `useRef(false)` 마운트 표시, `form.resendUnknown`·`settleApplied` 직접 호출이 없다. `use-app-form.ts`에 `resendLeftUnknown` 같은 재전송 결과 재판정이 없다. 지난 세 결함(1105/08-02·08-04, 1106/08-02)의 시험이 platform hook 시험(`tests/component/`)으로 옮겨져 통과한다 | +| RED 시험 아이디어 | platform 시험: 같은 mutation 정의를 쓰는 폼 두 개(기능 둘)를 그리고, 하나에서 결과 불명을 만든 뒤 내렸다 다시 그린다. 두 폼이 같은 hook으로 같은 막기·피드백을 보이는지 본다. 지금은 hook이 없어 쓸 수 없고, 생성 페이지 사본을 grep하는 정적 시험(`mutation.state.indicator`가 생성 출력에 있으면 실패)이 지금 실패한다 | +| 결정의 근거·대안 | 대안 A: 지금처럼 사본을 두고 CHANGELOG로 이식 안내(비용: 기능 수 × 수정 수). 대안 B: 위 platform hook(비용: 폼 API 추가, 생성 출력 변경. 생성 기능 이행 한 번). 대안 C: 폼에 코디네이터 상태만 주입하고 페이지 판정은 남김(절반). B를 권한다. 소유자 결정이 필요하면 결정 대기로 둔다(공개 API 추가) | + +### R-02 재마운트한 폼에서 재전송하면 보낸 적 없는 화면 값을 제출 값으로 쓴다 + +| 칸 | 내용 | +| --- | --- | +| 성격 | 확인된 결함 | +| 관련 관점 | 1, 23, 28 | +| 심각도·우선순위 | Low·P3. 쓰기는 맞다(원래 요청을 같은 키로 보낸다). 잃는 것은 사용자가 재마운트 뒤 입력한, 보낸 적 없는 값이다. 템플릿이 그리는 경로(KEYED 작성 페이지)에서 닿는다 | +| 통제 | M1 — 같은 상황의 다른 출구(`settleApplied`)에는 규칙이 구현돼 있다(`use-app-form.ts:236-246`). 재전송 출구에는 없다. 이 경로의 시험 없음(`tests/component/form-foundation.test.tsx`의 재전송 시험은 재마운트를 다루지 않는다) | +| 증거 | E1 | +| 근거 | `resendUnknown`이 `const submittedValues = unknownSubmissionRef.current ?? values;`(`src/presentation/forms/use-app-form.ts:425`, 주석 `:424` "After a remount the form no longer holds the submitted values"). 성공이면 `applyOutcome(outcome, submittedValues)` → `settleSuccessfulValues(화면 값)`(`:437`, `:261-263`) → 기본 `resetOnSuccess`면 값과 기준값을 기본값으로 되돌리고, 아니면 화면 값을 기준값으로 삼아 dirty를 끈다(`:218-229`). 재전송이 결과 불명으로 남으면 `unknownSubmissionRef.current = submittedValues`(화면 값)(`:430-435`). 그 뒤 「변경됨으로 확인」은 `settleApplied`가 그 값을 제출 값으로 보고 같은 정리를 한다(`:235`, `:248`). 반대로 `settleApplied`의 재마운트 분기는 "The values on screen were never sent, so they and the dirty state stay as they are"(`:237-241`). CHANGELOG도 "화면의 값과 기준값은 그대로 둔다. 그 값은 보낸 적이 없어서, 입력이 남아 있으면 이탈 확인도 남는다"고 약속한다(`CHANGELOG.md:196`) | +| 발생 조건 | KEYED 작성 페이지에서 저장 중 떠났다 돌아온다(채널이 UNKNOWN을 유지, `application-query.ts:982-995`). 폼은 새로 마운트되어 `unknownSubmissionRef`가 비어 있다. 사용자가 필드에 입력한 뒤 「같은 요청으로 다시 보내기」를 누른다. 또는 재전송이 429·503 `RATE_LIMIT_*`로 결과 불명에 남은 뒤 「변경됨으로 확인」을 누른다 | +| 영향 | 보낸 적 없는 입력이 지워지거나 깨끗한 값으로 표시되고, 이탈 확인 없이 사라진다. 생성 페이지는 재전송 성공 때 `pending` 중에 상세로 이동하므로(`scripts/create-feature-write-slice.ts:680`, `:744`) 가드도 없다 | +| 최소 개선 방향 | 재전송 경로도 `unknownSubmissionRef.current`가 없으면 화면 값을 제출 값으로 쓰지 않는다. 성공이면 `settleApplied`의 재마운트 분기와 같은 처리(결과만 success, 값·기준값 유지). 결과 불명에 남으면 `unknownSubmissionRef`에 화면 값을 넣지 않고 "제출 값 모름" 표시를 따로 둔다. R-01을 고치면 이 분기는 hook 하나로 모인다 | +| 완료 기준 | 재마운트 뒤 재전송 성공·재전송 결과 불명→확인 두 경우 모두 화면 값과 dirty가 그대로다. 아래 RED 시험 통과 | +| RED 시험 아이디어 | 실험 X-L1-01(4절). 새 폼(`unknownSubmissionRef` 없음)에 값을 입력하고 `resendUnknown(async () => ({ ok: true, value }))`를 부른다. 지금은 값이 `""`로 되고 `dirty=false`다. 고친 뒤 값 유지, `dirty=true` | +| 선택 비교 칸 | 적용 제외 — 이미 정한 규칙(`settleApplied` 재마운트 분기)을 다른 출구에 맞추는 일이다 | + +### R-03 생성 기능의 입력이 scope fence로 끊긴 요청을 실패 telemetry로 보낸다 + +| 칸 | 내용 | +| --- | --- | +| 성격 | 확인된 결함 | +| 관련 관점 | 6, 8, 24 | +| 심각도·우선순위 | Low·P3. 사용자 피해 없음. 생성 기능 전부가 복제하는 기본값이다 | +| 통제 | M2 — 호출자 abort(`REQUEST_ABORTED`)만 빼는 코드와 시험이 있다. fence abort는 없다 | +| 증거 | E1 | +| 근거 | 생성된 `createFeatureInput`의 `reported`가 `result.error.kind !== "REQUEST_ABORTED"`일 때 `.list.failed` 등을 warning으로 보낸다(`scripts/create-feature.ts:940-948`). scope fence로 끊긴 요청은 `REQUEST_ABORTED`가 아니라 `SCOPE_GENERATION_CHANGED`다: 전송 중 fence → `TRANSPORT_FAILURE` `ABORTED_BY_SCOPE`(`src/adapters/http/http-execution-v3.ts:720-732`), 응답 뒤 fence → `CONTRACT_VIOLATION` `SCOPE_FENCED`(`:1854-1858`). 바인딩이 둘 다 `SCOPE_GENERATION_CHANGED`로 바꾼다(`src/adapters/http/feature-http-binding.ts:509-516`, `:557-558`). 생성 입력 시험은 호출자 abort만 본다(`scripts/create-feature.ts:1271-1281`). 테스트 전략은 "aborted request는 terminal error나 telemetry failure로 오분류되지 않는다"(`docs/design/2026-07-26-frontend-platform-testing-strategy-design.md` 7.1절), 렌즈 체크리스트도 같다 | +| 발생 조건 | 목록·상세 GET이나 작성이 진행 중일 때 로그아웃·계정 전환·subject 없는 재알림으로 scope가 fence된다(`src/adapters/query-cache/server-state-scope-runtime.ts:120-147`) | +| 영향 | 로그아웃마다 진행 중 요청 수만큼 `.*.failed` warning이 쌓여 실패율 지표가 부풀고, 진짜 실패와 섞인다 | +| 최소 개선 방향 | abort 판정을 한 곳에 둔다: `src/contracts/errors.ts`에 `isAbortFailure(failure)`(`REQUEST_ABORTED`, `SCOPE_GENERATION_CHANGED`)를 두고 템플릿의 `reported`가 그것을 쓴다(템플릿마다 kind를 손으로 적지 않는다). 생성 입력 시험에 fence 경우를 더한다. 이미 생성한 기능 이행은 R-01과 같은 문제다 | +| 완료 기준 | 생성 입력 시험에 `SCOPE_GENERATION_CHANGED` 실패가 emit을 부르지 않는 경우가 있고 통과한다 | +| RED 시험 아이디어 | 실험 X-L1-02. 생성 입력 시험 템플릿에 fence 경우를 더해 생성·실행하면 지금 실패한다 | +| 선택 비교 칸 | 적용 제외 — 계약 문서의 abort 규칙을 생성 코드에 맞추는 일이다 | + +### R-04 query·mutation 실패 진단이 원인을 버린다 + +| 칸 | 내용 | +| --- | --- | +| 성격 | 확인된 결함 | +| 관련 관점 | 8, 24, 6 | +| 심각도·우선순위 | Low·P3. 진단 품질 | +| 통제 | 미확인(이 동작을 보는 시험을 찾지 못함. `tests/unit/query-cache.test.ts`는 `createQueryCacheAdapter`만 본다) | +| 증거 | E1 | +| 근거 | (1) 운영 QueryClient(`src/bootstrap/runtime-adapters.ts:388`)의 `QueryCache`·`MutationCache` `onError`가 모든 실패를 `cache.operation.failed`(warn)로 남긴다(`src/adapters/query-cache/tanstack-query-cache.ts:39-44`, `:24-35`). `useApplicationQuery`·`useApplicationMutation`은 실패한 결과마다 `ApplicationQueryError`를 던진다(`src/presentation/adapters/query/application-query.ts:167`, `:478`). 이 오류는 `kind`가 없고(`failure.kind`만 있다, `:54-62`) `safeErrorKind`는 `kind` 다음 `name`을 읽으므로(`src/contracts/diagnostics.ts:241-266`) 모든 기록이 `error_kind: APPLICATION_QUERY_ERROR`다. 404, 필드 거절, 결과 불명, scope fence로 끊긴 mutation(`REQUEST_ABORTED`·`SCOPE_GENERATION_CHANGED`)이 모두 "cache 작업 실패" 한 가지로 남는다. (2) 예상 밖 throw를 정규화할 때 정의 이름을 버린다: `operationId: "APPLICATION_QUERY"`(`application-query.ts:173-177`, 같은 함수가 `:127`·`:137`에서는 `queryDefinitionId`를 씀), `"APPLICATION_MUTATION"`(`:702-705`, `:759-763`, 같은 함수가 `:510-513`에서는 `definitionId`를 씀) | +| 발생 조건 | 실패한 query·mutation 전부(1). execute·낙관적 update·무효화 설치 누락이 던질 때(2) | +| 영향 | 진단에서 실패 종류를 가를 수 없고, 사용자 입력 거절과 abort가 warn "cache operation failed"로 세어진다(결함 패턴 C6). 예상 밖 throw는 어느 정의에서 났는지 모른다 | +| 최소 개선 방향 | (1) `onError`는 `ApplicationQueryError`(서버·실행기 답)를 cache 실패로 세지 않거나, 센다면 `failure.kind`를 싣고 abort kind는 뺀다. (2) 두 리터럴을 `queryDefinitionId`·`definitionId`로 바꾼다 | +| 완료 기준 | 필드 거절·abort로 끝난 mutation 뒤 `cache.operation.failed` 기록이 없다(또는 kind가 실린다). 예상 밖 throw 실패의 `operationId`가 정의 ID다 | +| RED 시험 아이디어 | 실험 X-L1-03 | +| 선택 비교 칸 | 적용 제외 — 진단 누락 수정 | + +### R-05 `useApplicationQuery`가 파생 값(stale 실패)을 effect로 state에 복사하고, 다시 시도의 초기화가 바로 덮인다 + +| 칸 | 내용 | +| --- | --- | +| 성격 | 확인된 결함(렌즈 위반은 코드로 확인, 화면 깜빡임은 미검증) | +| 관련 관점 | 1, 5 | +| 심각도·우선순위 | Low·P3 | +| 통제 | 미확인 — 최종 상태만 보는 시험이 있다(`tests/component/application-query-bridge.test.tsx:15-49`). 다시 시도 중 표시는 시험이 없다 | +| 증거 | E1 | +| 근거 | `staleFailure`를 `useState`로 두고 effect에서 `query.isError && hasData`면 `true`, 성공이면 `false`로 쓴다(`src/presentation/adapters/query/application-query.ts:103`, `:185-191`). TanStack v5는 data가 있으면 재조회 중에도 `status: "error"`를 유지하므로 이 값은 렌더 중 계산과 같다. `retry`가 `setStaleFailure(false)` 뒤 refetch하지만(`:193-196`) refetch가 `isFetching`을 바꾸면 effect가 다시 돌아 `true`로 되돌린다(`:186-187`). `deriveAsyncState`는 `stale-degraded`를 `refreshing`보다 먼저 고른다(`src/application/view-models/async-state.ts:118-129`). 렌즈: "파생할 수 있는 값을 state에 복사하지 않고 렌더 중에 계산한다", "effect는 외부 시스템 동기화에만" | +| 발생 조건 | 데이터가 있는 query의 배경 재조회 실패 → 「다시 시도」 | +| 영향 | 매 전이마다 렌더가 한 번 더 돈다. 다시 시도 중에 "갱신 중"이 아니라 "오래된 데이터 + 다시 시도" 버튼이 다시 보인다(추론). `retry`의 초기화는 사실상 죽은 코드다 | +| 최소 개선 방향 | `const staleFailure = query.isError && hasData`로 렌더 중에 계산하고 effect·state를 지운다. 다시 시도 중에 `refreshing`을 보이려면 `isStale: staleFailure && !query.isFetching`처럼 같은 줄에서 정한다(보일 상태는 fe-ux가 정한다) | +| 완료 기준 | 이 hook에 `setStaleFailure`·그 effect가 없다. 다시 시도 중 indicator를 단언하는 시험이 통과한다 | +| RED 시험 아이디어 | 실험 X-L1-04 | +| 선택 비교 칸 | 적용 제외 — 렌즈 기준 위반 정리 | + +### R-06 "모든 시도가 받는 거절" 판정이 기능 `mapProblem`이 바꿀 수 있는 `failure.code`를 읽는다 + +| 칸 | 내용 | +| --- | --- | +| 성격 | 구조적 위험 | +| 관련 관점 | 6, 17, 22, 23 | +| 심각도·우선순위 | Low·P3. 기능 작성자가 `mapProblem`에서 code를 바꿔야 닿는다. 템플릿과 매뉴얼 예시는 code를 그대로 넘긴다 | +| 통제 | M2 — 판정은 한 함수다(`src/contracts/errors.ts:273-279`). 입력이 백엔드 code라는 보장은 없다 | +| 증거 | E1 | +| 근거 | `isRefusedOnEveryAttempt`는 `failure.code`와 `failure.httpStatus`로 짝 백엔드 표(400 `VALIDATION_FAILED`, 400 `IDEMPOTENCY_KEY_INVALID`)를 본다(`errors.ts:256-279`). 그런데 PROBLEM 실패의 `code`는 기능 `mapProblem`이 준 값이 먼저다(`src/adapters/http/feature-http-binding.ts:340-341`, `:447-450`). effect는 실행기가 백엔드 code로 정한다(`src/adapters/http/backend-envelope.ts:363-374`). 주석은 kind를 읽지 않는 이유를 "a feature's `mapProblem` sets it"이라고 적지만(`errors.ts:270-271`) code도 같은 곳에서 정해진다. Envelope 없는 백엔드(매뉴얼 02 4절 예)의 code에도 짝 백엔드 표가 그대로 적용된다 | +| 발생 조건 | (a) 기능이 선언한 쓰기 전 거절 code(예: `WORKLOG_INVALID`)를 `mapProblem`에서 `code: "VALIDATION_FAILED"`로 바꾼다 → 결과 불명 요청의 재전송이 그 답을 받으면 요청을 정리한다. 결정 D10 보완은 "기능이 선언한 code는 결과 불명을 풀지 않는다"(`docs/architecture/backend-api-and-server-state-contract.md` 6.1절). (b) 반대로 백엔드 400 `VALIDATION_FAILED`를 기능 code로 바꾸면 재전송 거절이 결과 불명을 풀지 못해 폼이 "나중에 다시 보내기"에 머문다 | +| 영향 | (a) 정리된 뒤 다음 저장이 새 키로 나간다. 첫 시도가 적용됐다면 중복이 생길 수 있다(결함 패턴 C2와 같은 모양, 조건이 좁다). (b) 사용자가 고칠 수 있는 입력 오류에서 막힌다 | +| 최소 개선 방향 | 판정 입력을 백엔드 답에서 고정한다. 바인딩이 Envelope operation의 `outcome.problem.code`와 status로 "모든 시도가 받는 거절" 여부를 계산해 `AppFailure`에 따로 싣고(예: `refusal: "EVERY_ATTEMPT"`), `isRefusedOnEveryAttempt`는 그 칸만 읽는다. Envelope 없는 operation은 싣지 않는다(안전한 쪽) | +| 완료 기준 | `mapProblem`이 code를 바꿔도 (a)·(b) 모두 결정 D10 보완대로 동작한다 | +| RED 시험 아이디어 | 통합 시험(`tests/integration/`): 실제 실행기 + 바인딩 + `useApplicationMutation`. KEYED Envelope create에 `refusedBeforeWrite: ["WORKLOG_INVALID"]`, `mapProblem`이 그 code를 `{ kind: "VALIDATION_REJECTED", code: "VALIDATION_FAILED" }`로 바꾼다. 첫 요청 응답 유실 → 재전송이 400 `WORKLOG_INVALID` → 지금은 `indicator === null`(정리됨), 고친 뒤 `mutation-effect-unknown`. (실험으로는 요청하지 않는다. 시험 작성이 필요하다) | +| 선택 비교 칸 | 대안: 바인딩이 `mapProblem`의 code가 플랫폼 표의 code와 겹치면 거절하는 조립 검사(더 단순, 그러나 (b)는 못 막는다). 위 안을 권한다 | + +## 3. 넘길 것 + +- → fe-ux: R-05에서 다시 시도 중에 보일 상태(`refreshing`인지 `stale-degraded` 유지인지)를 정한다. R-01 hook을 만들 때 재인증 실패 뒤(코디네이터는 결과 불명, 폼은 `reauth-required`) 생성 작성 페이지가 sign-in 버튼 없는 상태만 보이고 결과 불명 버튼은 필드를 고쳐야 다시 나오는 흐름을 볼 것(`scripts/create-feature-write-slice.ts:724-730`, `use-app-form.ts:297-303`). 매뉴얼 8단계가 "onRetry만 넘긴다"고 적어 둔 범위라 이 렌즈의 결함으로 올리지 않았다. +- → fe-testing: 생성 작성 페이지 시험이 1초 고정 대기로 "상세로 가지 않음"을 단언한다(`scripts/create-feature-write-slice.ts:984-990`). 부정 단언이라 대기가 필요하지만 시간 가정 시험(결함 패턴 T3)인지 판정이 필요하다. +- → fe-structure: `src/presentation/pages/home-page.tsx:31-47`과 `src/presentation/examples/platform-overview-page.tsx:396-412`의 릴리스 요약 effect가 같은 사본이다(아직 갈라지지 않음). 한 hook으로 모을지. +- → 총괄: desktop 게이트 summary는 FE-GATE-020이 진행 중이었고 013 rc=1이다. D8 조건(`parts` 뒤 명령 rc=0)은 확인하지 않았다. + +## 4. 실험 요청 + +모두 desktop, 작업 폴더 되돌림 필요. env 없음(기본), 시간 상한 각 5분. + +### X-L1-01 (R-02) 재마운트 뒤 재전송이 화면 값을 지우는지 + +- 명령: `scripts/verify.sh exec -- node scripts/run-vitest.ts run tests/component/r9-l1-form-resend-remount.test.tsx` +- 기대: 지금 실패(값 `""`, `dirty=false`). 실패가 R-02의 증거(E2)다. +- 패치(새 파일): + +```diff +--- /dev/null ++++ b/tests/component/r9-l1-form-resend-remount.test.tsx +@@ -0,0 +1,27 @@ ++// @vitest-environment jsdom ++ ++import { act, renderHook } from "@testing-library/react"; ++import { z } from "zod"; ++import { describe, expect, it } from "vitest"; ++ ++import { useAppForm } from "../../src/presentation/forms/index.ts"; ++ ++describe("r9 L1 probe", () => { ++ it("keeps values a remounted form never sent when its resend succeeds", async () => { ++ const hook = renderHook(() => ++ useAppForm({ ++ schema: z.object({ name: z.string() }).strict(), ++ defaultValues: { name: "" }, ++ allowedServerFields: ["name"], ++ mapToCommand: (values: { name: string }) => values, ++ submit: async () => ({ ok: true as const, value: "unused" }), ++ }), ++ ); ++ act(() => hook.result.current.setValue("name", "typed after remount")); ++ await act(() => ++ hook.result.current.resendUnknown(async () => ({ ok: true as const, value: "saved" })), ++ ); ++ expect(hook.result.current.values.name).toBe("typed after remount"); ++ expect(hook.result.current.dirty).toBe(true); ++ }); ++}); +``` + +### X-L1-02 (R-03) 생성 입력이 fence abort를 telemetry로 보내는지 + +- 명령: `scripts/verify.sh exec -- sh -c 'corepack pnpm create:feature typecheck-probe-fence && node scripts/run-vitest.ts run tests/features/typecheck-probe-fence/typecheck-probe-fence-feature-input.test.ts'` +- 기대: 새 경우 1건 실패(emit 1회 호출). 나머지 통과. +- 패치(템플릿에 경우 추가): + +```diff +--- a/scripts/create-feature.ts ++++ b/scripts/create-feature.ts +@@ -1280,5 +1280,17 @@ function renderInputTest({ names, operationId }: Shape): string { + await expect(input.listItems()).resolves.toEqual({ ok: false, error: failure }); + expect(emit).not.toHaveBeenCalled(); + }); ++ ++ it("does not report a load the session fence aborted", async () => { ++ const failure = createFailure("SCOPE_GENERATION_CHANGED", "${operationId}", 0, { code: "ABORTED_BY_SCOPE" }); ++ const emit = vi.fn(); ++ const input = create${pascal}FeatureInput( ++ gatewayListing(async () => ({ ok: false, error: failure })), ++ { telemetry: { emit } }, ++ ); ++ ++ await expect(input.listItems()).resolves.toEqual({ ok: false, error: failure }); ++ expect(emit).not.toHaveBeenCalled(); ++ }); + }); + `; + } +``` + +### X-L1-03 (R-04) 실패한 mutation이 `cache.operation.failed`를 남기는지 + +- 명령: `scripts/verify.sh exec -- node scripts/run-vitest.ts run tests/unit/r9-l1-query-cache-diagnostics.test.ts` +- 기대: 지금 실패(기록 1건, `error_kind: APPLICATION_QUERY_ERROR`). 기록 내용이 R-04 증거다. +- 패치(새 파일): + +```diff +--- /dev/null ++++ b/tests/unit/r9-l1-query-cache-diagnostics.test.ts +@@ -0,0 +1,24 @@ ++import { describe, expect, it } from "vitest"; ++ ++import { createQueryClient } from "../../src/adapters/query-cache/index.ts"; ++ ++describe("r9 L1 probe", () => { ++ it("does not count a refused save as a cache operation failure", async () => { ++ const records: unknown[] = []; ++ const client = createQueryClient({ ++ diagnostics: { record: (event: unknown) => void records.push(event) } as never, ++ }); ++ const answer = Object.assign(new Error("VALIDATION_REJECTED"), { ++ name: "ApplicationQueryError", ++ failure: { kind: "VALIDATION_REJECTED", effect: "NOT_APPLIED" }, ++ }); ++ await client ++ .getMutationCache() ++ .build(client, { mutationFn: async () => { throw answer; } }) ++ .execute(undefined) ++ .catch(() => undefined); ++ console.log(JSON.stringify(records)); ++ expect(records).toEqual([]); ++ }); ++}); +``` + +(`createQueryClient`가 배럴에 없으면 `../../src/adapters/query-cache/tanstack-query-cache.ts`에서 가져온다.) + +### X-L1-04 (R-05) 다시 시도 중 indicator + +- 명령: `scripts/verify.sh exec -- node scripts/run-vitest.ts run tests/component/application-query-bridge.test.tsx` +- 기대: 새 경우가 지금 실패(다시 시도 중 `stale-degraded`). 통과하면 R-05의 화면 영향 부분을 지우고 렌즈 위반(파생 state)만 남긴다. +- 패치: + +```diff +--- a/tests/component/application-query-bridge.test.tsx ++++ b/tests/component/application-query-bridge.test.tsx +@@ -49,6 +49,40 @@ describe("application query inbound bridge", () => { + expect(execute).toHaveBeenCalledTimes(3); + }); + ++ it("r9 L1 probe: does not show the stale failure again while its retry runs", async () => { ++ const client = queryClient(); ++ let release: ((value: ApplicationResult) => void) | undefined; ++ let calls = 0; ++ const execute = vi.fn(() => { ++ calls += 1; ++ if (calls === 1) return Promise.resolve({ ok: true as const, value: ["first"] }); ++ if (calls === 2) { ++ return Promise.resolve({ ++ ok: false as const, ++ error: createFailure("SERVER_FAILURE", "LIST", 0), ++ }); ++ } ++ return new Promise>((resolve) => { ++ release = resolve; ++ }); ++ }); ++ const hook = renderHook( ++ () => useApplicationQuery({ queryKey: ["resource", "r9-retry"], execute }), ++ { wrapper: wrapper(client) }, ++ ); ++ await waitFor(() => expect(hook.result.current.data).toEqual(["first"])); ++ await act(() => hook.result.current.retry()); ++ await waitFor(() => expect(hook.result.current.state.indicator).toBe("stale-degraded")); ++ act(() => { ++ void hook.result.current.retry(); ++ }); ++ await waitFor(() => expect(execute).toHaveBeenCalledTimes(3)); ++ await act(async () => { ++ await Promise.resolve(); ++ }); ++ expect(hook.result.current.state.indicator).not.toBe("stale-degraded"); ++ act(() => release?.({ ok: true, value: ["recovered"] })); ++ await waitFor(() => expect(hook.result.current.state.indicator).toBeNull()); ++ }); ++ + it("coalesces repeated manual retries while stale data is refetching", async () => { +``` + +## 5. 결함 아님으로 판정한 의심 + +- 생성 목록·상세 페이지가 `onAction`을 넘기지 않아 401·403·404에 버튼이 없다 — 매뉴얼 8단계가 그렇게 정하고 `use--failure-action` 조각을 준다(`docs/manual/01-add-a-feature.md:588-619`). +- scope fence가 결과 불명 admission을 버려 재로그인 뒤 새 키가 된다(`application-query.ts:964-978`) — 런북 6.3-7에 적힌 한계(`docs/operations/api-contract-and-server-state-recovery.md:280`)이고 지난 라운드들이 판정했다. +- `useApplicationMutation`의 LEGACY 실행 분기 — 1101 결정 08-03(테스트 4건 때문에 유지)이다. +- KEYED 재전송이 기능 선언 code(`_INVALID`)로 거절되면 "나중에 다시 보내기"에 머문다 — 결정 D10 보완("기능이 선언한 code는 결과 불명을 풀지 않는다")대로다. +- `bindQuery`가 렌더마다 identity binding을 새로 만들어 `useApplicationQuery`의 lease effect가 렌더마다 돈다(`application-query.ts:104-107`) — 외부 자원 lease 동기화라 effect 용도가 맞고, 정리 순서상 row가 0으로 내려간 채 다른 intern을 만나지 않는다(`query-keys.ts:247-299`). +- 첫 렌더에 결과 불명 채널이 아직 없어 `submit`이 `UNKNOWN_EFFECT_CHANNEL_LIMIT_EXCEEDED`를 낼 수 있다(`application-query.ts:391-411`, `:556-574`) — 채널은 마운트 effect에서 잡히고, 클릭은 그 뒤에 처리된다. 실제로 닿는 순서를 보이지 못했다. +- 결과 불명 재전송 대기 `setTimeout`이 unmount에 취소되지 않는다(`application-query.ts:689-695`) — 사용자가 시작한 재전송이고, 대기 뒤 `mutationFn`이 scope를 다시 본다(`:439-448`). mutation은 취소가 안전할 때만 취소한다는 렌즈 기준에 맞다. +- `RenderErrorBoundary`의 custom fallback 함수가 `reset`을 받지 않는다(`src/presentation/boundaries/render-error-boundary.tsx:62-66`) — 라우터의 fallback은 `RENDER_FAILURE`의 registry action(`reload-once`)대로 사용자 reload를 주고, `resetKey`(경로+검색값)가 라우트 이동 때 reset한다(`src/presentation/routes/app-router.tsx:409-418`). 사용자 버튼이라 "제한 없는 reload" 금지에도 해당하지 않는다. +- `OVERLOADED_BEFORE_SEND`(클라이언트 트래픽 예산)가 kind `NETWORK_UNREACHABLE`로 보인다(`feature-http-binding.ts:509-516`) — code가 `OVERLOADED_BEFORE_SEND`로 남고 effect `NOT_STARTED`, action `retry`가 맞다. 문구 차이는 fe-ux 몫이다. +- `HomePage`가 릴리스 요약을 effect + setState로 읽는다(`home-page.tsx:34-47`) — 백엔드 서버 상태가 아니라 부팅 때 읽은 릴리스 manifest이고 정리(`active` 플래그)가 있다. +- 짝 백엔드 code 이름 규칙(`_INVALID`) — 백엔드 `new-feature.sh:56`의 upper snake와 프론트 `namesOf`(`scripts/create-feature.ts:142-157`)가 같은 결과를 낸다(PascalCase ↔ kebab). +- `REFUSALS_OF_EVERY_ATTEMPT`가 `REFUSED_BEFORE_WRITE`의 손 사본이다 — `tests/unit/backend-envelope.test.ts:186-230`가 부분집합 관계를 대조한다(구조적 위험은 통제됨). +- 생성 목록 `measureItems`의 `itemCount`와 `LIST_STANDARD.maxResultItems: 200` — 백엔드 page `size` 상한 100 안이다. diff --git a/docs/reviews/2026-11-round9-02-structure-contracts.md b/docs/reviews/2026-11-round9-02-structure-contracts.md new file mode 100644 index 00000000..3ac91251 --- /dev/null +++ b/docs/reviews/2026-11-round9-02-structure-contracts.md @@ -0,0 +1,243 @@ +# round9 L2 — 구조·SRP·공통 계약 리뷰 결과 + +> round9 리뷰(2026-11-12, 대상 main `5250ff95`)의 영역 기록이다. 서브에이전트가 쓴 원문을 그대로 옮겼다. 바꾼 것은 이 인용 블록과, 작업 폴더 절대 경로를 `(작업 폴더)`로 줄인 것뿐이다. 발견 ID는 이 파일의 이름표(R-01 등)이고, 라운드 ID(`1112/NN-MM`)와의 대응은 [README](2026-11-round9-review.md) 15절이다. + + +대상: 프론트 `5250ff95`(tree `75cc3752`), 짝 백엔드 main `a7e38c10`(읽기만). repo 파일은 고치지 않았다. + +## 0. 결론 + +- 판정: **고칠 것 있음.** High 이상 없음. Medium 없음. Low 10건(P2 둘, P3 여덟). +- 계층 방향, 배럴 경계, kernel 셋, 기능·context 경계는 지금 코드에서 모두 지켜진다. 직접 만든 import 그래프로 규칙 31개를 다시 대 봤고 위반 0이다. desktop FE-GATE-010도 같은 tree에서 rc=0이다. +- 약한 곳은 **규칙을 지키는 장치 쪽**이다. 꼭 지킬 것 2의 kernel 규칙은 회귀 fixture가 없다. 파일 단위 예외 둘은 실제 쓰임보다 넓어서, presentation이 adapter에 닿는 길이 규칙 밖으로 열려 있다. 예외 목록과 ratchet 상한은 실제와 어긋났다. +- 짝 계약은 판정이 맞다. code 집합, Envelope 모양, 멱등성 응답, 단계 판정이 백엔드 main 코드와 같다. 다만 pin이 백엔드 main보다 238커밋 뒤에 있다. 그사이 백엔드가 폴더를 다시 배치하고 샘플을 지워서, drift 검사가 지금 실패할 상태다. 6.1절이 근거로 든 파일 넷과 경로 셋도 main에 없다. + +## 1. 범위 + +**읽은 경로** + +- 정본: 루트 `AGENTS.md`, `docs/architecture/layers.md` 전부, `docs/work/reference/structure.md` 전부, `review-criteria.md`, `decisions.md`, `defect-patterns.md` 3·4절, `experts.md`, `.claude/agents/{reviewer,arch-reviewer}.md` +- 규칙과 검사: `.dependency-cruiser.json` 전부, `scripts/check-architecture.ts` 전부, `scripts/check-adapter-inventory.ts` 전부, `scripts/check-backend-contract-drift.ts` 전부, `scripts/lib/{architecture-lint-fixtures,repository-layout}.ts`, `scripts/verify-documentation-readiness.ts` 125~275행, `tests/architecture/{feature-adapter-reach,observability-boundaries}.test.ts`, `tests/unit/repository-layout.test.ts` 100~228행, `tests/fixtures/architecture/**` 목록 +- 소스: `src/adapters/*/index.ts` 16개, `src/adapters/platform/*` 10개(머리와 import), `browser-file-storage/result.ts`, `cross-context-invalidation/index.ts`, `src/{contracts,platform,contexts,apps,bootstrap,features,adapters,application,presentation}/AGENTS.md`, `src/contracts/{errors,mutation-intent,external-contract-runtime,server-state}.ts` 바뀐 곳, `src/adapters/http/backend-envelope.ts` 전부, `src/bootstrap/runtime-adapters.ts` 185~620행, `src/features/{feature-adapter-contribution,product-capabilities}.ts`, `src/platform/routing/context-route-module.ts` import, `src/presentation/{pages/home-page,templates/page-templates}.tsx` import +- 문서: `docs/architecture/` 11개. `contract-ownership.md`, `overview.md`, `layers.md`, `backend-api-and-server-state-contract.md` 1~40행·127~410행은 줄 단위로 읽었다. 나머지는 구조 주장을 grep으로 대조했다. `docs/reviews/adapters/INVENTORY.md`, `config/contracts/*.json` +- 짝 백엔드(읽기만): `docs/web/http-contract.md` 1절, `git diff 45d2a478..a7e38c10`(http-contract.md, 생성기 템플릿, `new-feature.sh`, `IdempotencyExecutor`, `GlobalExceptionHandler`, 오류 code registry, fileserver), `ApiError.java`, `ResponseMeta.java`, `RateLimitInterceptor.java`, `RateLimitTransportError.java`, `OperationalError.java`, `IdempotencyKeyHeader.java`, `WebMvcRequestIdFilter.java`, `FileserverErrorCode.java` +- 직접 만든 도구: scratchpad `tools/graph.py`. `src/**/*.ts(x)` 377파일의 import edge 1199개를 정규식으로 뽑아 규칙 31개(`$1` 치환 포함)를 대 본다. 결과는 위반 0이다. 해석하지 못한 것은 생성물 `src/.generated/*` 셋뿐이다. + +**쓴 스킬과 그 기준으로 본 것** + +- `fe-structure` 함정 1~12와 체크리스트. 배럴 우회, 파일 단위 kernel 예외, 루트 파일의 adapter 재수출(함정 4), 갈라진 복사본(6), 손 사본(7), 제품 소유 자리(8), INVENTORY 동시 수정(9), 공개 표면 시그니처(11), bootstrap의 판정(12), 예외의 `comment`와 폭. +- SRP: 이유 두 가지로 바뀌는 모듈. `check-adapter-inventory.ts`, `runtime-adapters.ts`, `contracts/errors.ts`, `backend-envelope.ts`를 봤다. +- 공통 계약 ①: `src/contracts/`가 판정 한 곳인지 봤다. `REFUSALS_OF_EVERY_ATTEMPT`, `PLATFORM_CODES_POSSIBLY_AFTER_WRITE`, `isValidIdempotencyKey`. +- 공통 계약 ②: pin, 6.1절, `backend-envelope.ts`를 백엔드 main 코드와 대조했다. + +**게이트 결과**(`desktop:/tmp/claude-gates/r9fe-base/summary.txt`, tree `75cc3752` = 이 HEAD의 tree, CI env이며 실제 runner가 아니다) + +- FE-GATE-001~012는 rc=0이다(010 architecture 56s 포함). +- FE-GATE-013은 rc=1이다. 이 렌즈 몫이 아니고 D8 판정 대상이다. +- FE-GATE-020은 읽은 시각(21:06 이후)에 아직 돌고 있었다. + +**확인 못 한 것** + +- FE-GATE-020의 결과. +- snapshot의 `artifacts/quality/dependency-report.json`. 아직 없어서 그래프 요약(모듈 수, fixture 32개 통과)을 실행 결과로 확인하지 못했다. +- 노트북에서는 node·vitest를 돌리지 않았다. 아래 발견은 모두 E1이다. +- R5 검사(`tests/unit/example-feature-rules.test.ts`, 331행이 바뀜)의 내부 판정은 읽지 않았다. fe-testing으로 넘긴다. +- `scale-architecture.md`(1408행)는 줄 단위로 읽지 않았다. +- desktop의 백엔드 checkout은 `3d73b6f1`이라 main(`a7e38c10`)이 아니다. drift 실험(X-01)에는 main checkout이 따로 필요하다. + +## 2. 발견 + +### S-01 kernel 규칙(꼭 지킬 것 2)을 고정하는 회귀 fixture가 없다 + +| 칸 | 내용 | +| --- | --- | +| 성격 | 구조적 위험 | +| 관점 | 21, 2, 10 | +| 심각도·우선순위 | Low · P2. 꼭 지킬 것 2의 유일한 기계 판정이 규칙 파일 한 줄에 걸려 있고, 그 줄이 바뀌어도 아무것도 실패하지 않는다 | +| 통제 | 지금의 위반 import는 M3다(`check:architecture`). 규칙 자체를 지키는 장치는 M0다 | +| 증거 | E1. X-02로 E2까지 올릴 수 있다 | +| 근거 | `.dependency-cruiser.json:252-263`. `scripts/check-architecture.ts:796-1039`의 assertion 32개 중 `adapters-do-not-know-other-concrete-adapters`나 kernel 셋을 이름으로 드는 것이 없다. `tests/fixtures/architecture/dependency-graph/`에도 adapter끼리의 fixture 폴더가 없다(barrel·cross-boundary·import-boundaries·layer·cycle·unresolved·allowed뿐). `scripts/verify-documentation-readiness.ts:148-149`는 json의 규칙이 문서에 있는지만 본다. 문서에 있는 규칙이 json에서 빠진 경우는 보지 않는다. `tests/architecture/`에도 이 규칙을 읽는 시험이 없다. 다른 핵심 규칙(배럴, 기능·context 간, 루트 재수출)은 fixture가 거절과 허용을 고정한다(`check-architecture.ts:799-919`) | +| 발생 조건 | 누가 adapter끼리 import를 통과시키려고 `pathNot`을 `^src/adapters/`로 넓히거나 규칙을 지운다. 그 뒤 실제 adapter 간 import를 더한다 | +| 영향 | 꼭 지킬 것 2가 조용히 꺼진다. `fe-structure` 「검증」은 "규칙을 꺼 본 사본에서 그 fixture 검사가 실패해야 한다"고 요구하는데, 이 규칙에는 그 fixture가 없다 | +| 최소 개선 방향 | `dependency-graph/kernel/` fixture를 더한다. 거절: `adapters/alpha/x.ts → adapters/beta/y.ts`, `adapters/alpha/x.ts → adapters/browser-file-storage/other.ts`. 허용: 같은 그룹, `adapters/platform/*`, `browser-file-storage/result.ts`, `cross-context-invalidation/index.ts`. 이 다섯을 `runGraphFixtureChecks`의 assertion으로 둔다 | +| 완료 기준 | X-02a·X-02b 두 변이에서 `check:architecture`가 실패하고, 원래 규칙에서는 통과한다 | +| RED 시험 | 위 fixture와 assertion을 먼저 넣고 X-02a 패치를 건다. 지금은 넓힌 규칙에서 "kernel 밖 adapter 간 import 거절" assertion이 실패한다. 이 실패가 RED이고, 원래 규칙으로 돌리면 통과(GREEN)한다. 변이 전후를 모두 기록한다 | + +### S-02 파일 단위 예외 둘이 실제 쓰임보다 넓어, presentation이 adapter에 닿는 길이 규칙 밖에 있다 + +| 칸 | 내용 | +| --- | --- | +| 성격 | 구조적 위험(결함 패턴 S5) | +| 관점 | 2, 22, 21 | +| 심각도·우선순위 | Low · P3. 같은 모양의 0929/02-06, 1101/05-04와 같은 등급이다 | +| 통제 | 예외의 뜻은 `comment`에 M1로 적혀 있다. 넓은 부분을 막는 장치는 없다(M0) | +| 증거 | E1. X-03으로 E2까지 올릴 수 있다 | +| 근거 | (1) `.dependency-cruiser.json:337-348` `platform-kernel-is-product-neutral`. `pathNot: ^src/platform/routing/`이 금지 대상 일곱(features·contexts·apps·adapters·bootstrap·presentation·application)을 모두 푼다. 실제 쓰임은 apps·contexts의 type 두 줄이다(`src/platform/routing/context-route-module.ts:2-3`). `concrete-adapters-compose-only-in-bootstrap`(`:139-149`)은 `src/platform`을 다루지 않는다. 그래서 routing에서 adapter 배럴로 가는 edge를 거절하는 규칙이 하나도 없다. presentation은 routing을 import한다(`src/presentation/routes/app-router.tsx:39`). (2) `:301-312` `feature-and-app-roots-do-not-reach-adapters`. `pathNot`이 `src/features/feature-adapter-contribution.ts`의 모든 adapter import를 푼다. 쓰는 것은 type 하나다(`feature-adapter-contribution.ts:5-7`, comment "type only"). 그래프는 type-only를 구별하지 않는다(`scripts/check-architecture.ts:403-408`). `tests/architecture/feature-adapter-reach.test.ts:50-53`은 이 파일을 아무 import나 받는 예외로 고정한다. 범용 presentation이 이 루트 파일을 import하는 것을 막는 규칙도 없다(`generic-presentation-…`은 `installed-`만 본다). 이 두 길이 바로 `layers.md:73-76`이 막으려던 "간선 하나씩 검사의 빈틈"이다 | +| 발생 조건 | routing 파일이나 contribution 파일에서 `export { … } from "…/adapters/http/index.ts"`를 쓰고, presentation이 그것을 import한다 | +| 영향 | 다른 규칙이 모두 통과한 채로 presentation이 HTTP adapter를 직접 부를 수 있다(`presentation-does-not-fetch-directly` 우회) | +| 최소 개선 방향 | (1) routing 예외를 대상으로 좁힌다. 규칙을 둘로 나눠 routing은 `^src/(apps\|contexts)/`만 허용한다. 또는 `to.pathNot`로 apps·contexts만 푼다. (2) contribution 파일은 adapter를 type으로만 import하게 강제한다. 방법은 둘이다. 그래프가 Babel의 `importKind`/`exportKind`를 읽어 예외 파일의 value edge를 거절한다. 또는 그 type을 application port로 옮긴다(comment의 재검토 조건) | +| 완료 기준 | X-03 패치에서 `check:architecture`가 두 edge 모두를 거절한다 | +| RED 시험 | `cross-boundary` fixture에 둘을 더한다. `platform/routing/reexport.ts → adapters/telemetry/index.ts`와 `features/feature-adapter-contribution.ts`의 value re-export에 거절 assertion을 둔다. 지금 규칙에서는 둘 다 실패하고, 좁힌 뒤 통과한다 | + +### S-03 파일 단위 예외 목록이 실제 쓰임과 이미 어긋났다 + +| 칸 | 내용 | +| --- | --- | +| 성격 | 확인된 결함(S5, 그리고 손 사본이 이미 다른 S1) | +| 관점 | 2, 21, 23, 9 | +| 심각도·우선순위 | Low · P3 | +| 통제 | M1(comment) | +| 증거 | E1 | +| 근거 | (1) `.dependency-cruiser.json:234`의 `generic-presentation-does-not-compose-the-product` 예외 목록에 `pages/home-page.tsx`가 있다. 그런데 그 파일은 registry를 읽지 않는다. import는 `src/presentation/pages/home-page.tsx:1-7`이 전부이고 `installed-`는 없다. `f849d781`(2026-11-06)에서 읽기를 그만뒀는데 목록은 그대로다. 규칙 comment(`:230`)는 "remove each file from the list as it stops reading the registries"라고 약속하고, `layers.md:110-111`은 "registry를 읽는 새 모듈은 gate에서 실패한다"고 적는다. (2) `design-system-is-reached-through-its-index`의 예외(`:73`, `:77`)는 이유로 "`PaginationLandmarkContext`가 index에 없다"를 든다. 그런데 `src/presentation/templates/page-templates.tsx:5-8`은 index가 이미 export하는 `LinkButton`도 primitive 파일에서 직접 가져온다(`design-system/index.ts:17-21`). (3) `layers.md:107-118`의 "kernel 말고 예외" 목록에 두 예외가 빠졌다. 하나는 `feature-adapter-contribution.ts`다(같은 문서 `:67`의 규칙 행에는 있다). 다른 하나는 `page-templates.tsx`의 디자인 시스템 예외다 | +| 발생 조건 | home-page.tsx가 다시 registry를 읽어도, page-templates.tsx가 다른 primitive를 깊게 import해도 게이트가 통과한다 | +| 영향 | 예외가 목적보다 넓다. 문서의 예외 목록을 믿는 리뷰어는 둘을 놓친다 | +| 최소 개선 방향 | `home-page.tsx`를 `pathNot`에서 뺀다. `page-templates.tsx`는 `LinkButton`을 index로 가져온다. `layers.md` 예외 목록에 두 행을 더한다 | +| 완료 기준 | 예외 목록의 파일마다 그 예외가 필요한 edge가 실제로 있다 | +| RED 시험 | `check-architecture.ts`에 "예외로 이름 붙은 파일은 그 규칙의 `to.path`에 맞는 edge를 하나 이상 가진다" 검사를 더한다. 지금은 `home-page.tsx`에서 실패하고, 목록에서 빼면 통과한다 | + +### S-04 hand-rolled abort ratchet 상한이 실제보다 하나 크고, 머리 주석이 낡았다 + +| 칸 | 내용 | +| --- | --- | +| 성격 | 확인된 결함 | +| 관점 | 21, 9, 23 | +| 심각도·우선순위 | Low · P3 | +| 통제 | M3. ratchet은 있지만 여유가 1이다 | +| 증거 | E1. 같은 조건으로 다시 셌다: `addEventListener("abort")`가 있고 `platform/abortable-operation.ts`를 부르지 않는 `src/adapters`(platform 제외) 파일은 12개다 | +| 근거 | `scripts/check-adapter-inventory.ts:216` `HAND_ROLLED_ABORT_CEILING = 13`, 판정은 `:230`(`>`). 13→12는 `src/adapters/http/client.ts` 삭제(V2 HTTP 경로 삭제, 2026-11-03) 때 일어났다(`4d172590`과 HEAD의 목록 diff). `:212-213` 주석은 "이행으로 숫자가 내려가면 이 상수도 같이 내린다"고 약속한다. `:135-139` 주석의 "`image-cdn-runtime.ts`와 `resumable-upload-runtime.ts`는 … 지금도 자기 abort 사본을 들고 있다. 어댑터 전체로는 23개"는 사실과 다르다. 두 파일 모두 지금 kernel을 import하고, 남은 파일은 12개다 | +| 발생 조건 | 새 adapter 파일 하나가 kernel 대신 손으로 abort를 엮는다 | +| 영향 | ratchet이 한 번은 막지 못한다 | +| 최소 개선 방향 | 상한을 12로 내리고 머리 주석의 낡은 문장을 지운다. 또는 판정을 `!==`로 바꿔 줄었을 때도 상수를 내리게 강제한다 | +| 완료 기준 | 상한이 실제 개수와 같다 | +| RED 시험 | 상한과 실제 개수가 다르면 실패하는 검사를 둔다. 지금 12≠13으로 실패하고, 12로 내리면 통과한다 | + +### S-05 짝 계약 pin이 백엔드 main보다 238커밋 뒤이고, drift 검사가 실패할 상태다 + +| 칸 | 내용 | +| --- | --- | +| 성격 | 미검증(판정은 맞음, 근거 위치가 낡음) | +| 관점 | 17, 26, 21, 9 | +| 심각도·우선순위 | Low · P2. 지원 구성의 짝 경로에 닿는 계약이지만 판정 자체는 main에서도 맞다(아래 대조) | +| 통제 | M1(절차 문장) + 게이트 밖 수동 drift 검사 | +| 증거 | E1(두 repo의 git 객체를 읽음). X-01로 E2까지 올릴 수 있다 | +| 근거 | pin은 `45d2a478`이다(`config/contracts/backend-contract-pin.json:5`, comparedOn 2026-11-05). 백엔드 main `a7e38c10`까지 238커밋이 있다. 그사이 바뀐 것은 셋이다. (1) `docs/web/http-contract.md` 끝 주석 2줄(`9d6c67c14`). 표는 그대로다. drift 검사(`scripts/check-backend-contract-drift.ts:153-166`)는 문서가 바뀌면 실패한다. (2) pin의 `scaffoldSources` 6개 중 3개 경로(`…/templates/src/domain-core/…/__Feature__.java.tmpl`, `…/application-core/…/__Feature__ErrorCode.java.tmpl`, `…/application-core/…/Create__Feature__UseCase.java.tmpl`)가 `1388c06a9`(relayout)로 `src/domain/core/`, `src/application/core/`로 옮겨졌다. 내용 변경은 0줄이다. `:169-179`의 `git diff pin..HEAD -- <옛 경로>`는 삭제를 diff로 보고 실패한다. (3) `ab5982e95`(샘플 삭제)로 `docs/architecture/backend-api-and-server-state-contract.md` 6.1절이 근거로 든 파일 넷이 main에 없다. `PosterImagePublicationController`(`:306`), `WorkLogWebMapper`·`RepoStatsAclMapper`(`:310`), `DomainExceptionHandler`(`:291`, `:313`)다. 「파일 위치」 목록의 `src/application-core/`, `src/sample-portfolio/`, `src/application-fileserver/`(`:348-356`)도 main에 없다. 참조 도메인 행의 code(`WORKLOG_*`, `POSTER_*`, `:313`)도 main에 없다. `IDEMPOTENCY_KEY_INVALID`를 내는 컨트롤러는 main에 하나도 없다. 4.1절은 "짝 백엔드를 새로 받을 때마다 돌린다", "기준 커밋을 올리면 pin, 답 표, 6.1절 표를 같은 변경에서 다시 확인한다"고 적는다 | +| main과 대조해 같은 것 | 오류 code registry 60개 집합이 같다(diff는 `log_level` 줄 삭제뿐). `ApiError(code, category, message, retryable, details)`와 `ResponseMeta(requestId, traceId, correlationId, page)`가 `backend-envelope.ts:45-77` 스키마와 맞는다. `meta` id 정규식은 백엔드 `WebMvcRequestIdFilter.java:68`의 상위 집합이다. §2·§4 표가 pin과 같다. `RATE_LIMIT_*`는 `RateLimitInterceptor.java:58,63`(preHandle)에서만 나오고 503이다. `IDEMPOTENT_*`·`IDEMPOTENCY_*` status가 `OperationalError.java:47-53`과 같다. `IdempotencyExecutor`는 주석만 바뀌었다. `GlobalExceptionHandler.java:95,209`의 원인 사슬 탐색은 code별 단계를 바꾸지 않는다. 키 문법(`IdempotencyKeyHeader.java:30`, 1~256 가시 ASCII)이 `src/contracts/mutation-intent.ts:38,42`와 같다. fileserver code 표가 같다. 바뀐 것은 admin `@Valid` 하나로, 컨트롤러 전 단계라 판정이 같다 | +| 발생 조건 | 짝 백엔드 main으로 drift를 돌리거나, 6.1절 근거를 main에서 열어 본다 | +| 영향 | drift가 exit 1이라 "새로 받을 때마다 돌린다"는 절차가 막힌다. 판정 근거를 main에서 찾는 사람은 없는 파일을 찾는다 | +| 최소 개선 방향 | pin을 `a7e38c10`으로 올린다. 순서는 넷이다. `--write-excerpt`로 사본을 다시 옮긴다. `scaffoldSources`의 세 경로를 새 위치로 고친다. 6.1절의 파일:줄과 위치 목록을 main 기준으로 다시 적는다. 참조 도메인 행은 "샘플과 함께 사라짐"으로 바꾸거나 지운다. 같은 변경에서 답 표와 `PLATFORM_CODES_POSSIBLY_AFTER_WRITE`를 다시 확인한다 | +| 완료 기준 | 백엔드 main checkout으로 drift가 exit 0이다. `verify:documentation`의 짝 경로 검사가 새 pin tree에서 통과한다 | +| RED 시험 | X-01이 지금 exit 1이다(RED). pin을 올린 뒤 exit 0이다 | + +### S-06 현재 계약 문서 둘이 기록 문서(설계서)를 정본으로 삼고, 그 설계서는 다시 현재 문서를 정본이라 한다 + +| 칸 | 내용 | +| --- | --- | +| 성격 | 확인된 결함 | +| 관점 | 9, 4, 23 | +| 심각도·우선순위 | Low · P3 | +| 통제 | M0(검사 없음) | +| 증거 | E1 | +| 근거 | `docs/architecture/backend-api-and-server-state-contract.md:3-8`와 `docs/architecture/static-delivery.md:3-8`이 「정본 안내」로 `docs/design/2026-07-30-…-closed-deep-design.md`를 "정본"이라 하고 "충돌하면 정본을 따른다"고 적는다. 그 설계서의 머리 블록(`:7`)은 "현재 정본: `docs/architecture/frontend-application-foundation.md`, `src/bootstrap/`"이다. `docs/README.md:70`은 "설계서와 기록은 … 지금 동작을 설명하지 않는다"고 적고, `docs/work/reference/structure.md:55`는 "현재 계약 문서는 작업 이력 문서에 기대지 않는다"고 적는다. 2026-11-08에 설계서를 `docs/design/`로 옮길 때 두 머리 문단을 고치지 않았다 | +| 발생 조건 | 짝 계약 문서를 읽는 사람이 런타임 결정의 정본을 찾는다 | +| 영향 | 정본이 서로를 가리키는 고리가 된다. 지금 동작과 다를 수 있는 기록을 정본으로 따르게 된다 | +| 최소 개선 방향 | 두 머리 문단을 「현재 정본: `frontend-application-foundation.md`, `src/bootstrap/`. 설계 배경: 그 설계서」로 바꾼다 | +| 완료 기준 | 살아 있는 문서가 `docs/design/` 문서를 "정본"이라 부르지 않는다 | +| RED 시험 | 문서 검사에 "살아 있는 문서에서 `docs/design/` 링크와 '정본'이 같은 문장에 오면 실패"를 더한다. 지금 두 파일에서 실패하고, 고친 뒤 통과한다 | + +### S-07 구조 정본을 가리키는 문장 넷이 낡았다 + +| 칸 | 내용 | +| --- | --- | +| 성격 | 확인된 결함 | +| 관점 | 9, 23, 4 | +| 심각도·우선순위 | Low · P3 | +| 통제 | M0. `1b3eee41`의 절 이름 대조 시험은 `.claude/skills/`만 본다 | +| 증거 | E1 | +| 근거 | (1) `src/contracts/AGENTS.md:3`과 `docs/work/reference/structure.md:24`가 `contract-ownership.md` 「Decision rule」을 가리킨다. 그 절 제목은 이제 「판단 규칙」이다(`docs/architecture/contract-ownership.md:6`). `fe-structure` 스킬은 맞게 적는다. (2) `src/contracts/AGENTS.md:16`은 "짝 백엔드 계약 pin과 대조 테스트(FE-GATE-007)"라고 적는다. 대조 테스트 `tests/unit/backend-contract-pin.test.ts`·`backend-contract-pin-document.test.ts`는 `test:unit`, 곧 FE-GATE-005다(`config/ci/gates.json` FE-GATE-005 `test-unit`). `fe-react` 스킬은 005로 맞게 적는다. (3) `docs/work/reference/structure.md:87`은 "pin과 drift 검사는 아직 계약 문서 글자만 비교하고, 답 표 JSON과 생성기 사실은 대조 밖이다"라고 적는다. 지금 drift는 답 표를 pin 사본과 대조하고(`check-backend-contract-drift.ts:146-151`), 생성기 원본 파일이 바뀌었는지도 본다(`:169-179`). 남은 빈틈은 "옮긴 사실의 내용 대조"뿐이다 | +| 발생 조건 | 이 문서를 따라 절이나 게이트를 찾는다 | +| 영향 | 없는 절을 찾고, 틀린 게이트를 돌린다 | +| 최소 개선 방향 | 세 문장을 고친다. 절 이름 대조 시험의 범위를 `AGENTS.md`(루트와 `src/*`), `docs/work/`까지 넓힌다 | +| 완료 기준 | 넓힌 시험이 통과한다 | +| RED 시험 | 대조 시험에 `src/*/AGENTS.md`와 `docs/work/**/*.md`를 더한다. 지금 「Decision rule」 두 곳에서 실패하고, 고치면 통과한다 | + +### S-08 INVENTORY 머리·꼬리 문장이 표와 다르다 + +| 칸 | 내용 | +| --- | --- | +| 성격 | 확인된 결함 | +| 관점 | 9, 23 | +| 심각도·우선순위 | Low · P3 | +| 통제 | 행 집합은 M3(`check:adapter-inventory`)다. 문장은 M0다 | +| 증거 | E1. 표 143행 = `git ls-files src/adapters` 143개를 다시 확인했다 | +| 근거 | `docs/reviews/adapters/INVENTORY.md:7`은 "결과 119개를 하나씩 고정한 coverage ledger"라고 적는데 표는 143행이다. `:155`는 "새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다"고 적는다. 그러나 링크한 상세 리뷰에 없는 행이 7개다. `01-network-and-state.md`에 `http/feature-http-binding.ts`, `http/http-retry-lifecycle.ts`, `platform/{abortable-operation,bounded-capacity,indexeddb-connection,indexeddb-transaction}.ts`, `query-cache/cursor-pagination-contract.ts`가 없다. 그리고 `.claude/rules/docs.md`는 리뷰 영역 문서를 리뷰 뒤에 고치지 못하게 한다. 꼬리 문장이 지킬 수 없는 약속이다 | +| 최소 개선 방향 | 머리 블록의 "119개"를 지운다(숫자를 옮겨 적지 않는다). 꼬리 문장을 "이 ledger를 같은 변경에서 고친다. 상세 리뷰는 기록이라 고치지 않는다"로 바꾼다 | +| 완료 기준 | 두 문장이 표·규칙과 맞다 | +| RED 시험 | 해당 없음(문장 수정). 원하면 `check:adapter-inventory`가 머리 블록에 숫자가 있으면 실패하게 한다 | + +### S-09 `check-adapter-inventory.ts`가 서로 무관한 검사 다섯을 한 스크립트에 둔다(SRP) + +| 칸 | 내용 | +| --- | --- | +| 성격 | 개선 제안 | +| 관점 | 22, 8, 4 | +| 심각도·우선순위 | Low · P3 | +| 통제 | — | +| 증거 | E1 | +| 근거 | `scripts/check-adapter-inventory.ts`에 다섯 검사가 있다. adapter 목록(`:57-75`), SW 자산 확장자 표(`:77-95`), 시험 fixture의 node_modules 링크 방식(`:97-128`), abort 커널 필수 소비자(`:130-187`), abort ratchet(`:189-238`). 바뀌는 이유가 다섯이다. 특히 fixture node_modules 규칙은 adapter와 무관한데 `check:adapter-inventory`라는 이름 아래에 있다. 이 규칙을 찾는 사람은 이름으로 찾지 못한다 | +| 최소 개선 방향 | adapter 목록과 abort 둘만 남긴다. SW 자산 표는 SW 생성기 검사로, fixture 링크는 fixture 시험(`tests/unit/fixture-node-modules.test.ts`)이나 별도 check로 옮긴다. 게이트 ID는 그대로 둔다 | +| 완료 기준 | 스크립트 이름이 그 안의 검사를 다 설명한다 | +| RED 시험 | 해당 없음(구조 정리). 옮긴 뒤 각 검사의 거절 변이가 새 위치에서 실패하는지 본다 | + +### S-10 bootstrap이 "자격 증명 주인" 판정 순서를 두 함수에 따로 적는다(SRP·판정은 한 곳에) + +| 칸 | 내용 | +| --- | --- | +| 성격 | 구조적 위험(손 사본이 아직 같음) | +| 관점 | 22, 23, 1, 15 | +| 심각도·우선순위 | Low · P3 | +| 통제 | 미확인(두 함수를 함께 지나는 시험은 찾지 않았다) | +| 증거 | E1 | +| 근거 | `src/bootstrap/runtime-adapters.ts:540-590` `attachCredentials`는 scope → ANONYMOUS 프로필 → 제품 provider → 세션 순서로 판정한다. `:598-620` `reportServerUnauthenticated`는 같은 순서(ANONYMOUS → 제품 provider → 세션)를 다시 적는다. 주석에 "decided in the same order as `attachCredentials`"라고 쓰여 있다. `src/bootstrap/AGENTS.md`는 "판정·정책은 application·platform·기능 폴더에 둔다"고 적고, `structure.md` 6절은 "판정 규칙은 한 곳에"라고 적는다 | +| 발생 조건 | 프로필 종류나 제품 provider 규칙을 한쪽만 고친다 | +| 영향 | 401이 엉뚱한 주인에게 간다. 예를 들어 제품 credential의 401로 세션이 로그아웃된다 | +| 최소 개선 방향 | `resolveCredentialOwner(authProfileId): "NONE" \| "PRODUCT" \| "SESSION"` 하나를 두고 두 함수가 그것을 읽는다. 위치는 bootstrap 안이어도 되고 application 정책이어도 된다 | +| 완료 기준 | 순서가 한 곳에만 있다 | +| RED 시험 | 프로필 셋(ANONYMOUS, 제품, 세션)마다 "붙인 주인 = 401을 받는 주인"을 단언하는 시험을 둔다. 한쪽 순서만 바꾸는 변이에서 실패해야 한다 | + +## 3. 넘길 것 + +- fe-testing: (1) R2 검사 `tests/unit/repository-layout.test.ts:107-147` `literalRootLists`는 ts/js 코드의 배열 리터럴만 본다. sh·py·json(정책 파일 하나 빼고)·yaml 안의 루트 목록이 거짓 통과하는지 확인한다. (2) R5 검사 `tests/unit/example-feature-rules.test.ts`가 소유자를 따라가는 판정에 빈 입력이나 첫 줄 return이 없는지 확인한다. (3) S-01·S-02 fixture 설계. 이 렌즈는 규칙의 폭만 판정했다. +- fe-security: S-10의 401 전달 순서. 두 함수를 함께 지나는 시험이 있는지, 어긋날 때의 피해를 본다. 백엔드 W4 수정(`FileserverAdminController` `@Valid`)은 프론트 판정에 영향이 없다. 컨트롤러 전 단계라 `VALIDATION_FAILED`가 `NOT_APPLIED` 그대로다. +- 총괄: S-05의 pin 이동은 짝 계약 변경이라 크기가 큼이다(`docs/work/README.md` 2절). 백엔드에 넘길 것은 없다. 백엔드 쪽 문장(`http-contract.md` 끝 주석)은 프론트 문서를 맞게 가리킨다. + +## 4. 실험 요청 + +패치는 scratchpad `r1-L2-patches/`에 있고, 셋 모두 `git apply --check`를 통과했다. 실험마다 작업 폴더를 되돌린다. + +| ID | 명령 | env | 상한 | 변이 | 기대 | +| --- | --- | --- | --- | --- | --- | +| X-01 | `scripts/verify.sh exec -- node scripts/check-backend-contract-drift.ts --backend ` | 기본 | 3분 | 없음. desktop의 기본 옆 checkout은 `3d73b6f1`이라 main이 아니다. 총괄이 a7e38c10 worktree를 따로 준비한다 | exit 1. "docs/web/http-contract.md changed"와 scaffold source 3개("…domain-core…__Feature__.java.tmpl", "…application-core…ErrorCode…", "…application-core…Create__Feature__UseCase…")가 나온다. 이것이 S-05의 RED다 | +| X-02a | `scripts/verify.sh script check:architecture` | `CI=true` | 5분 | `X-02a-widen-kernel.patch`(kernel 규칙 `pathNot`을 `^src/adapters/`로 넓힘) | PASS(rc=0). kernel 규칙을 지키는 fixture가 없다는 것을 보인다(S-01) | +| X-02b | `scripts/verify.sh script check:architecture` 그리고 `scripts/verify.sh script verify:documentation` | `CI=true` | 각 5분 | `X-02b-delete-kernel-rule.patch`(규칙 객체 삭제, json 유효 확인함) | 둘 다 PASS. 문서 검사가 json에서 빠진 규칙을 보지 않는다는 것을 보인다(S-01) | +| X-03 | `scripts/verify.sh script check:architecture` | `CI=true` | 5분 | `X-03-reexport-holes.patch`. `src/platform/routing/http-reexport.ts`와 `feature-adapter-contribution.ts`가 http 배럴의 값을 재수출하고, `src/presentation/routes/x03-reach-http.ts`가 둘을 import한다 | PASS(rc=0). presentation이 규칙 밖 길로 HTTP adapter에 닿는다(S-02). 같은 변이로 `corepack pnpm lint`도 통과하는지 함께 보면 ESLint 쪽 빈틈도 확인된다(선택) | +| X-04 | `scripts/verify.sh script check:adapter-inventory` | `CI=true` | 2분 | 없음 | 출력에 "hand-rolled abort wiring: 12/13 files (ratchet) PASS"가 나온다(S-04 실측) | + +## 5. 결함 아님으로 판정한 의심 + +- adapter 사이 edge 26종: 모두 kernel 셋(platform 7파일, `browser-file-storage/result.ts`, `cross-context-invalidation/index.ts`)으로 간다. 내 그래프와 FE-GATE-010 rc=0이 같은 결론이다. +- 그룹 밖에서 adapter로 가는 edge 17개: 모두 그룹 `index.ts`(platform 배럴 포함)로 간다. 서브배럴이나 2단계 index로 가는 것은 없다. +- adapter 그룹 16개: 모두 `index.ts`가 있다. `bbde570` 뒤로 배럴 표면 변경은 0이다. +- `storage/*`가 `browser-file-storage/result.ts`를 import한다: `storage/indexeddb`·`storage/opfs`에서만이다. 제거 드릴이 함께 지우는 묶음이라 드릴을 깨지 않는다. +- `REFUSALS_OF_EVERY_ATTEMPT`(`src/contracts/errors.ts:256`)가 `REFUSED_BEFORE_WRITE`의 두 행을 손으로 옮겼다: `tests/unit/backend-envelope.test.ts:187-205`가 양쪽을 대조한다. 위치는 D10 보완 결정의 판정 자리다(`decisions.md` 2.2절). 손 사본이 아직 같고 대조 시험이 있어 결함이 아니다. +- kernel 폴더의 bootstrap 전용 서비스 둘(`browser-lifecycle.ts`, `browser-mutation-intent-factory.ts`): 1101/05-04 "고쳐짐 유지"(잔여 위험 기록)다. adapter의 import는 지금도 0이다. 다시 올리지 않는다. +- `createHttpObservationProjector`와 `isTerminalNonAbortFailure`가 bootstrap에 있다: VD-07 결정 기록이 정한 유일한 projection 자리다. +- 규칙과 문서에는 있는데 폴더가 없는 것: `src/adapters/web-worker`는 의도해서 비워 둔 자리다(`verify-documentation-readiness.ts:168-173` `NOT_CREATED`, 매뉴얼 03 189행). `src/domain`은 "지금은 없다"고 적혀 있다. +- `../../../clean-architecture-backend-template/…` 링크: 문서 검사가 pin 커밋의 tree로 확인하는 의도된 형식이다(`verify-documentation-readiness.ts:228-275`). +- facade 자신을 뺀 `pathNot`(lucide·zod·외부 계약·관측·loaded-feature-runtimes 자신)에 재검토 조건이 없다: 이것들은 단일 입구를 정의하는 것이지 예외가 아니다. `layers.md`도 예외 목록에 넣지 않는다. +- realtime을 고르면 템플릿 소유 규칙(`unselected-realtime-runtime-is-not-composed`)을 고쳐야 한다는 의심(S4): 지금은 조립이 realtime 선택 자체를 거절한다(`src/features/product-capabilities.ts:24-25`, 매뉴얼 03 185행). 막히는 지원 경로가 없다. +- `src/contracts`가 `src/platform`만 import하고 반대 방향은 0이다: `contract-ownership.md:34`와 같다. +- `bbde570` 뒤 공개 표면 변경(`server-state.ts`의 `resendSafe`): 선택 필드와 반환 필드를 더한 것뿐이라 BREAKING이 필요 없다. +- `check-architecture.ts`의 R2 변경(`inspectTypeScriptOnlyPolicy`): 등록부에서 고른 루트가 이전 하드코딩(src·scripts·tests·.storybook, 선택 recipes)과 같다. +- INVENTORY 행 집합: 추적 파일 143개와 정확히 같고 중복이 없다. +- 백엔드 생성 create와 `--keyed`: 매뉴얼이 "백엔드 create를 멱등성 executor 뒤에 둔 뒤에 쓴다"고 적는다(`docs/manual/reference/create-feature.md:18`). 알려진 전제라 결함이 아니다. +- 지시문 주입: 읽은 코드·문서에 리뷰어를 겨냥한 지시는 없었다. diff --git a/docs/reviews/2026-11-round9-03-testing-qa.md b/docs/reviews/2026-11-round9-03-testing-qa.md new file mode 100644 index 00000000..0bc36a99 --- /dev/null +++ b/docs/reviews/2026-11-round9-03-testing-qa.md @@ -0,0 +1,232 @@ +# round9 L3 — 시험(fe-testing·fe-qa) 전체 리뷰 + +> round9 리뷰(2026-11-12, 대상 main `5250ff95`)의 영역 기록이다. 서브에이전트가 쓴 원문을 그대로 옮겼다. 바꾼 것은 이 인용 블록과, 작업 폴더 절대 경로를 `(작업 폴더)`로 줄인 것뿐이다. 발견 ID는 이 파일의 이름표(R-01 등)이고, 라운드 ID(`1112/NN-MM`)와의 대응은 [README](2026-11-round9-review.md) 15절이다. + + +대상: `5250ff95`(tree `75cc3752`, origin/main). 노트북 worktree에서 읽기만 했다. repo 파일은 고치지 않았다. desktop은 `/tmp/claude-gates/r9fe-base/summary.txt`만 읽었다. + +## 0. 결론 + +- 판정: **고칠 것 있음.** High 이상 0건. Medium 1건, Low 8건, 개선 제안 1묶음. +- 특별 확인 후보(W1의 preload 말): **템플릿에는 해당하지 않는다.** 템플릿 fixture는 쓰이지 않은 preload를 세 엔진에서 직접 검사한다. WebKit 추정 경고는 문구 하나만 정확히 일치할 때 무시한다. 응답을 가로채는 CSP spec은 `fulfillBuildScript`를 쓴다. SW가 제어하는 문서는 `preloadunverifiable:service-worker:`로 이름 붙여 실패시키고, 그 줄은 SW update spec에서만 허용한다. tech-log main(`7a4e201a`)에는 `preload-use.ts`가 아예 없다. strict fixture도 `NO_COLOR`만 무시한다. 그래서 W1의 말은 tech-log가 이 파일을 아직 옮기지 않은 상태(또는 tech-log의 다른 작업본)를 본 것으로 판단한다. 5절 첫 줄에 근거를 적었다. +- 가장 큰 것: 감소된 움직임(reduced-motion) e2e가 `body`의 `animation-duration`을 보는데, 허용 값에 초기값 `"0s"`가 들어 있다. 그래서 규칙을 지워도 통과한다(T-01, Medium). + +## 1. 범위 + +| 항목 | 내용 | +|---|---| +| 렌즈 | `.claude/skills/fe-testing/SKILL.md`(함정 12, 점검표), `.claude/skills/fe-qa/SKILL.md`(함정 10, 회귀 점검표). 더해서 시험 GWT(준비 조건·행동·기대 결과가 드러나는가). GWT 표기 규칙은 이 repo에 없다(`docs/work/reference/testing.md` 전체 확인). 그래서 렌즈와 testing.md가 요구하는 것을 어긴 것만 결함으로 봤고, 나머지는 개선 제안으로 건수와 대표 위치만 적었다 | +| 기준 문서 | `docs/work/reference/testing.md` 전체, `docs/work/reference/defect-patterns.md` 2절(T1~T10)과 G7·G9, `docs/work/reference/review-criteria.md` 2·3·5·8절, `docs/work/reference/decisions.md`, `.claude/rules/tests.md`, `docs/testing/taxonomy.md` | +| 바뀐 곳 먼저 | `git diff --stat bbde570 5250ff95 -- tests vitest.config.ts 'playwright*.config.ts' config/testing config/ci/ungated-tests.json scripts/run-vitest.ts scripts/check-test-evidence.ts`: 201파일, +5,615/−5,137. 참조 기능 시험 22파일 삭제(`e3c8db48`), 생성 기능 e2e 신설, 갤러리 시험을 Storybook으로 이동, 자식 프로세스 timeout 규칙(`91962e24`) | +| 전부 읽음 | `tests/support/browser/preload-use.ts`, `strict-browser-test.ts`, `tests/e2e/preload-use.spec.ts`, `production-csp.spec.ts`, `service-worker-update.spec.ts`, `service-worker-recovery.spec.ts`, `boot-module-failure.spec.ts`, `old-tab-chunk-recovery.spec.ts`, `generated-feature.spec.ts`, `accessibility.spec.ts`, `scroll-restoration.spec.ts`, `typography.spec.ts`, `theme.spec.ts`, `tests/storybook/galleries.spec.ts`, `tests/visual/platform.visual.spec.ts`, `tests/browser-capabilities/chunk-load-error.spec.ts`, `tests/e2e/support/fixture-builds.ts`, `service-worker-builds.ts`(1~120), `vitest.config.ts`, `tests/setup.ts`, `tests/helpers/child-process-timeout.ts`, `tests/unit/child-process-timeout.test.ts`, `scripts/run-vitest.ts`, `scripts/check-test-evidence.ts`, `scripts/lib/no-skipped-tests-reporter.ts`, `scripts/lib/ungated-tests.ts`, `config/ci/ungated-tests.json`, `tests/unit/test-evidence-source-rules.test.ts`, `tests/mocks/server.ts`, Playwright 설정 5개 중 e2e·capabilities·storybook | +| 부분 읽음 | `tests/component/application-mutation-admission.test.tsx`(diff), `tests/integration/provider-guardian-transaction.test.ts`(`77c01b03` diff), `tests/browser-capabilities/opfs-runtime.spec.ts`(1~40, 180~275, 335~420), `cross-context-invalidation.spec.ts`(155~210), `indexeddb-runtime.spec.ts`(925~945), `image-cdn.spec.ts`(100~170), `storage-manager.spec.ts`, `browser-files.spec.ts`(450~470), `tests/unit/deletable-history-documents.test.ts`(1~80), `a11y-report.test.ts`(이름), `runtime-adapters-auth-profile.test.ts`(360~420), `scripts/scale/run-scale-profile.ts`, `scripts/scale/measure-feature-shape-growth.ts`(280~330), `scripts/test-feature-scaffold.ts`(60~100), `scripts/lib/build-environment.ts`, `src/adapters/http/backend-envelope.ts`(170~215), 짝 백엔드 `docs/web/http-contract.md` 4절·`docs/registries/error-codes.yaml` | +| fe-testing 기준으로 본 것 | 층 배치(바뀐 파일), MSW strict(`onUnhandledRequest: "error"` 4곳, `vi.fn()` fetcher는 "보내지 않음" 단언용만), 흔들림(실제 시계 대기, 고정 대기), 거짓 통과(이른 return, 초기값 허용, 허용 패턴 범위), 검출력(변이 예측), 검사기의 음성 fixture, 게이트 연결(ungated 6건 사유, 스크립트 경로 대조 377파일), timeout 규칙 | +| fe-qa 기준으로 본 것 | 로딩 화면 대신 라우트 h1을 기다리는가, 템플릿 원래 상태 밖(생성 기능 빌드) 시험, 실패·결과 불명·재전송 흐름, 두 탭, 콘솔 오류 처리(strict fixture 우회 지점), MSW·대역 응답이 짝 백엔드와 같은가 | +| 게이트 실행 결과(읽기만) | `summary.txt`: tree가 HEAD와 같다. FE-GATE-001~012 rc=0(008 201 s, 009 32 s), FE-GATE-013 rc=1(D8 판정 대상, 이 렌즈 몫 아님), FE-GATE-020 진행 중. 게이트 로그는 `PASS` 한 줄뿐이고 `snapshot/`이 아직 없다 | +| 확인 못 한 것 | (1) e2e·capability의 엔진별 통과·skip 수: snapshot 없음. (2) OPFS 05-01 시험이 어느 엔진에서 이른 return 하는지: 실행해야 안다(E-02). (3) 참조 기능 시험 약 3,000줄이 지키던 플랫폼 동작이 모두 옮겨졌는지 전수 대조하지 않았다. 표본 9개(sign-out 판정, intent 비노출, 중복 제거, fan-out, retry 겹침 등)는 대응 시험이 있다. (4) FE-GATE-029(`check:ci:gating`)는 main 단계라 이번 실행에 없다(E-05). (5) `tests/unit` 대부분과 `tests/component`·`tests/integration`의 바뀌지 않은 파일은 표본만 봤다 | + +## 2. 발견 + +### T-01 감소된 움직임 e2e가 규칙을 지워도 통과한다 + +| 칸 | 내용 | +|---|---| +| 성격 | 확인된 결함(거짓 통과, 코드로 확정. 실행 확인은 E-01) | +| 관련 관점 | 10, 21, 5 | +| 심각도·우선순위 | Medium · P2. 이 정책을 지키는 시험은 이것 하나다. 라우트 수동 검토 문서가 이 시험을 자동 증거로 적는다. 지금 규칙은 있어서 사용자 피해는 없다 | +| 통제 | 규칙 「동작 줄이기 설정이면 꼭 필요하지 않은 움직임을 멈춘다」: 목표 M3 / 확인 M2(CSS 규칙은 있다, 자동 검사는 효과 없음) | +| 증거 | E1 | +| 근거 | `tests/e2e/accessibility.spec.ts:130-137`이 `body`의 `getComputedStyle(body).animationDuration`을 읽고 `["0s", "0.00001s", "1e-05s"]` 안에 있으면 통과다. `body`에는 animation이 없다. 앱의 animation은 `.ui-spinner` 하나다(`src/presentation/styles/theme/primitives.css:108-117`, `ui-spin … infinite`). 규칙(`src/presentation/styles/theme/responsive.css:86-95`)이 없으면 `body`의 값은 초기값 `"0s"`이고, 이 값이 허용 목록에 있다. 다른 검사도 없다(`git grep -i "reduced-motion\|reducedMotion\|prefers-reduced" -- tests scripts eslint.config.ts config .storybook`: 이 시험 하나). `docs/accessibility/route-reviews/APP_HOME.md:18`은 "Automated … reduced-motion evidence is available"이라 적는다 | +| 발생 조건 | 누가 `responsive.css`의 미디어 블록을 지우거나 `*` 선택자를 좁히거나, 새 animation이 `!important` 규칙 밖에 생길 때 | +| 영향 | 전정 장애 사용자에게 움직임이 그대로 나가도 FE-GATE-008·009가 통과한다. 수동 검토(M7)는 아직 pending이라 뒤를 받치지 못한다 | +| 최소 개선 방향 | 움직이는 실제 요소를 본다. 같은 시험에서 스피너가 있는 화면(또는 페이지에 `.ui-spinner`를 하나 붙여)을 열고, 감소 설정 없을 때 `animation-iteration-count`가 `infinite`임을 먼저 단언한 뒤(전제), 감소 설정에서 `1`이고 duration이 0.01ms 이하임을 단언한다. 허용 목록에서 초기값 `"0s"`를 뺀다 | +| 완료 기준 | `responsive.css:86-95`를 지우는 변이에서 이 시험이 세 엔진 모두 실패한다. 변이 없이 세 엔진 통과 | +| RED 시험 아이디어 | 위 "전제 + 감소" 두 단언 시험. 지금 코드에서는 통과(규칙 있음), 변이를 넣으면 실패. 지금 시험은 변이에서도 통과(E-01로 확인) | + +### T-02 OPFS 05-01 브라우저 시험이 OPFS를 못 쓰면 단언 없이 통과하고, 증거는 "zero skipped"라 적는다 + +| 칸 | 내용 | +|---|---| +| 성격 | 구조적 위험(코드 모양은 확인) + 미검증(지금 그렇게 끝나는 엔진이 있는지) | +| 관련 관점 | 10, 21, 5 | +| 심각도·우선순위 | Low · P2. E-02에서 한 엔진이라도 이른 return이면 Medium · P1로 올린다(증거 검사가 틀린 답을 낸다, `review-criteria.md` 3절) | +| 통제 | 「skip은 quarantine으로만」: M3(`check-test-evidence.ts`)지만 `return`은 skip으로 세지 않아 이 자리에는 M1 | +| 증거 | E1 | +| 근거 | `tests/browser-capabilities/opfs-runtime.spec.ts:352`와 `:470`이 `if (!(await installOpfsTab(page, scope))) return;`이다. `installOpfsTab`은 지원 판정이 거절이면 `false`를 낸다(`:252`). 그때 두 시험(3 케이스)은 단언 0개로 passed가 된다. 같은 파일 첫 시험은 미지원이면 `UNSUPPORTED`를 단언한다(`:186-191`). 증거 검사는 junit의 ``만 보고 "zero skipped"를 찍는다(`scripts/verify-browser-capability-evidence.ts:61-62`, `:72`). 1105 리뷰는 WebKit이 기본 정책에서 거절돼 spec이 일찍 끝난다고 적었고(`docs/reviews/2026-11-05-maturity-review/05-adapters-storage-kernel.md:164`), 1106 리뷰는 실행 시간으로 보아 돈 것 같다고 추론만 했다(`docs/reviews/2026-11-06-maturity-review/11-tests-browser-release-scale.md:203`). 두 라운드 연속 「확인 못 한 것」으로 넘어왔다 | +| 발생 조건 | OPFS 지원 판정(`inspectBrowserOpfsSupport`, `src/adapters/storage/opfs/browser-opfs-runtime.ts:151-180`)이 거절하는 엔진·버전 | +| 영향 | 그 엔진에서 "다른 탭 purge가 진행 중 put을 기다린다"(1103/05-01 수정)를 아무도 보지 않는데 증거는 세 엔진 통과로 남는다 | +| 최소 개선 방향 | 이른 return 대신, 지원해야 하는 엔진에서는 `expect(await installOpfsTab(...)).toBe(true)`로 단언한다. 지원하지 않는 엔진이 정말 있으면 `test.skip(<엔진 조건>, 이유)` + quarantine 주석으로 이름을 남긴다(그러면 증거 검사가 skip으로 센다) | +| 완료 기준 | 두 자리에 조용한 `return`이 없다. E-02 패치(그 자리에서 실패시키기)에서 세 엔진 결과가 기록되고, 미지원 엔진은 skip으로 증거에 나타난다 | +| RED 시험 아이디어 | E-02의 패치 그대로. 미지원 엔진이 있으면 지금 그 엔진에서 실패한다 | + +### T-03 `check-test-evidence.ts`의 규칙 셋에 혼자 도는 거절 fixture가 없다 + +| 칸 | 내용 | +|---|---| +| 성격 | 확인된 결함(검사기 자기 보호 없음, 결함 패턴 G9) | +| 관련 관점 | 21, 10 | +| 심각도·우선순위 | Low · P2. FE-GATE-008이 돌리는 시험 품질 검사의 일부가 꺼져도 아무 게이트도 모른다 | +| 통제 | M1(규칙은 있고, 규칙을 지키는 시험은 없음) | +| 증거 | E1 | +| 근거 | (1) 화면 전체 mask 규칙(`scripts/check-test-evidence.ts:307-311`): fixture `tests/fixtures/test-evidence/forbidden/full-screen-mask.fixture`가 있지만, 혼자 돌리는 시험이 없다. `tests/unit/test-evidence-source-rules.test.ts:31-32` 주석은 "Each forbidden fixture is checked alone"이라 적지만 시험은 셋(focused·expired·unowned, `:34-50`)뿐이다. 디렉터리 전체를 돌리는 FE-GATE-029 명령은 기대 진단이 공통 접두어 `"Test evidence failed:"`(`config/ci/gates.json:118` 행)라, 다른 fixture 셋이 계속 실패하면 통과한다. (2) strict fixture 우회 규칙(`:391-399`)과 (3) Playwright 설정의 `forbidOnly` 확인(`:385-389`)은 `if (!fixtureMode && !scenarioOnly)`(`:368`) 안에 있어 fixture 모드에서 아예 돌지 않는다. 이 두 문구를 찾는 시험도 없다(`git grep -n "bypasses strict browser fixture\|missing forbidOnly" -- tests`: 0건) | +| 발생 조건 | 셋 중 한 규칙을 지우거나 정규식을 좁히는 변경 | +| 영향 | 화면 전체를 가린 시각 시험, strict fixture를 우회한 e2e spec이 FE-GATE-008을 통과한다 | +| 최소 개선 방향 | `test-evidence-source-rules.test.ts`에 mask fixture 하나만 돌리는 시험을 더한다. e2e 규칙 둘은 검사 대상 폴더·설정을 인자로 받게 하고(`--e2e-root`, `--playwright-config`), 우회 spec 하나와 `forbidOnly` 없는 설정 하나를 거절 fixture로 둔다 | +| 완료 기준 | 세 규칙 각각을 지우는 변이에서 시험이 하나씩 실패한다 | +| RED 시험 아이디어 | "rejects a screenshot mask over the whole UI": mask fixture 단독 실행이 rc=1과 `screenshot mask may not cover the whole UI`를 낸다. 지금은 시험이 없어서 E-03 변이(`:309-311` 삭제)가 살아남는다 | + +### T-04 strict fixture 강제가 `tests/e2e`의 문자열 포함 검사뿐이다 + +| 칸 | 내용 | +|---|---| +| 성격 | 구조적 위험(결함 패턴 G8) | +| 관련 관점 | 21, 23 | +| 심각도·우선순위 | Low · P3. 지금 우회하는 spec은 `chunk-load-error.spec.ts` 하나이고 이유가 있다 | +| 통제 | M3(e2e 폴더, 문자열) / M1(나머지 브라우저 폴더) | +| 증거 | E1 | +| 근거 | `scripts/check-test-evidence.ts:391-399`는 `tests/e2e/*.spec.ts`의 본문에 `"support/browser/strict-browser-test"` 글자가 있는지만 본다. 주석에 그 경로만 적어도 통과하고, 한 파일에서 맨 `test`를 섞어 써도 통과한다(`tests/e2e/preload-use.spec.ts:4`, `:111`, `:122`는 의도한 혼용). `tests/browser-capabilities`·`tests/visual`·`tests/storybook`은 검사하지 않는다. `tests/browser-capabilities/chunk-load-error.spec.ts:1`이 맨 `@playwright/test`를 쓴다(지난 리뷰가 이유를 받아들였다) | +| 발생 조건 | 새 capability·visual spec이 맨 `test`를 쓰거나, e2e spec이 주석에만 경로를 남길 때 | +| 영향 | 그 spec에서 콘솔 오류·pageerror·preload 검사가 조용히 빠진다(fe-qa 함정 9) | +| 최소 개선 방향 | ESLint `no-restricted-imports`로 `tests/{e2e,browser-capabilities,visual,storybook}/**/*.spec.ts`에서 `@playwright/test`의 값 `test` import를 막고, 의도한 파일 둘(`preload-use.spec.ts`, `chunk-load-error.spec.ts`)만 이유를 단 예외로 둔다. 문자열 검사는 지운다 | +| 완료 기준 | 맨 `test`를 쓰는 새 spec이 네 폴더 어디서든 lint에서 실패한다. 거절 fixture가 있다 | +| RED 시험 아이디어 | `tests/fixtures/architecture` 방식의 lint fixture: capability 폴더 spec 하나가 `import { test } from "@playwright/test"` → 지금은 아무 게이트도 실패하지 않음 | + +### T-05 두 번째 탭과 자기 context는 strict 검사 밖이다 + +| 칸 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 10, 12 | +| 심각도·우선순위 | Low · P3 | +| 통제 | M2(첫 `page`만) | +| 증거 | E1 | +| 근거 | strict fixture는 fixture의 `page` 하나에만 listener와 preload 추적을 붙인다(`tests/support/browser/strict-browser-test.ts:68-96`). 앱을 여는 두 번째 탭 7곳은 콘솔 오류·pageerror·requestfailed를 아무도 보지 않는다: `cross-context-invalidation.spec.ts:163`, `:226`, `opfs-runtime.spec.ts:341`, `:459`, `indexeddb-runtime.spec.ts:933`, `:985`, `:1190`. `tests/e2e/service-worker-recovery.spec.ts:94-150`은 고장 단계 때문에 자기 context를 쓰고 회복된 load만 손으로 검사한다. 그 검사는 preload 검사가 없고, WebKit 문구 무시도 없어 fixture와 갈라진 사본이다(`:135-150`). 회복된 문서는 SW 제어가 없다고 단언하므로(`:147-149`) `trackPreloadUse`를 붙일 수 있다 | +| 발생 조건 | 두 탭 경쟁 시험에서 두 번째 탭이 오류를 내는 회귀(fe-qa 함정 8의 자리) | +| 영향 | 두 탭 시나리오의 회귀가 첫 탭의 단언만으로 통과한다 | +| 최소 개선 방향 | strict 검사 본문을 `watchBrowserFailures(page)` 함수로 빼서 fixture와 두 번째 탭이 같이 쓰게 한다(같은 판정 `judge`). SW recovery는 마지막 `goto` 전에 그 함수와 `trackPreloadUse`를 붙인다 | +| 완료 기준 | 두 번째 탭에서 `console.error`를 내는 변이에서 그 시험이 실패한다. 손으로 쓴 검사 사본이 없다 | +| RED 시험 아이디어 | `cross-context-invalidation.spec.ts`의 두 번째 탭에서 `secondPage.evaluate(() => console.error("probe"))` → 지금은 통과 | + +### T-06 old-tab 시험의 preload 허용 절반이 닿지 않는 문서를 가리키고, 주석이 fixture 동작과 다르다 + +| 칸 | 내용 | +|---|---| +| 성격 | 구조적 위험(허용이 일으킨 실패보다 넓다) | +| 관련 관점 | 10, 9 | +| 심각도·우선순위 | Low · P3 | +| 통제 | M2 | +| 증거 | E1 | +| 근거 | 허용 정규식이 "A 탭에서 A 플랫폼 화면과 함께 preload된 청크"를 `preloadunused:` 허용에 넣는다(`tests/e2e/old-tab-chunk-recovery.spec.ts:181-188` 주석, `:195`). 그러나 preload 검사는 끝에 열려 있는 문서만 본다(`tests/support/browser/preload-use.ts:34-35`, `:217`). A 탭은 reload로 B 문서가 된다(`:241` `loads === 1`). 그래서 A 목록은 A 문서에 쓰일 일이 없고, B 문서에 같은 이름(공유 청크)으로 나타나는 "정말 안 쓴 preload"만 가릴 수 있다 | +| 발생 조건 | B 문서에서 공유 청크 preload가 실행되지 않는 회귀 | +| 영향 | 그 회귀를 이 시험이 놓친다. 지금 가린 실패는 없다(추론) | +| 최소 개선 방향 | A 목록을 지우고 B context routes 모듈 목록만 남긴다. 주석을 "B 탭의 것만"으로 고친다 | +| 완료 기준 | E-04에서 A 목록 없이 세 엔진 반복 통과 | +| RED 시험 아이디어 | 해당 없음(허용 축소). 축소 뒤 통과가 근거다 | + +### T-07 [w2-fe-2 파일] `ungated-tests.json`의 사유가 파일에 맞지 않는다 — 특히 순수 parser 시험 + +| 칸 | 내용 | +|---|---| +| 성격 | 확인된 결함(기준을 낮춘 예외의 사유가 사실과 다름). 0929부터 ID 없이 이월된 항목이고, 지금도 같다 | +| 관련 관점 | 21, 10, 26 | +| 심각도·우선순위 | Low · P3 | +| 통제 | M3(`check:ci:gating`이 목록에 없는 파일은 잡는다) / 사유 내용은 M0 | +| 증거 | E1 | +| 근거 | 6건 모두 같은 사유("baseline-regression이 기록한 CPU에서만 시간을 비교")다(`config/ci/ungated-tests.json`). 이 사유는 tier를 CI에서 안 도는 이유이지, 파일을 게이트에서 빼는 이유가 아니다. `tests/scale/tsc-diagnostics-parser.test.ts`(`:25`)는 문자열을 parse하는 순수 시험이다(`tests/scale/tsc-diagnostics-parser.test.ts:8-45`). 그 parser는 merge 게이트가 돌리는 측정이 쓴다(`scripts/scale/measure-feature-shape-growth.ts:307`, FE-GATE-020의 `scripts/test-feature-scaffold.ts:76-80`). 나머지 다섯도 개수·상한·가짜 시계를 단언한다(`tests/scale/session/long-session.test.ts:75`, `:149-150`, `network-flap.test.ts:88`, `telemetry-storm.test.ts:79-84`). 1103 리뷰의 변이 H57을 잡은 시험은 `long-session.test.ts` 하나였다(`docs/reviews/2026-11-03-maturity-review/10-tests-fast-layers.md:138`) | +| 발생 조건 | parser나 세션·telemetry 상한을 깨는 변경 | +| 영향 | merge 게이트 측정이 쓰는 parser의 오해석, 세션 정리 회귀를 merge에서 못 본다 | +| 최소 개선 방향 | `tsc-diagnostics-parser.test.ts`를 게이트 경로(예: `tests/unit` 또는 `test:coverage` 목록)로 옮기고 항목을 지운다(`ungatedTestFailures`가 남은 항목을 stale로 잡는다, `scripts/lib/ungated-tests.ts:104-106`). 나머지 다섯은 파일마다 실제 사유(실행 시간, 자식 프로세스 등)를 적거나 pr tier로 옮긴다. 결정이 필요하면 `decisions.md` 3절 형식으로 남긴다 | +| 완료 기준 | 남은 항목마다 그 파일에 맞는 사유가 있다. parser 시험이 merge 게이트에서 돈다 | +| RED 시험 아이디어 | parser의 `M` 단위 변환(`collect-tsc-diagnostics.ts` `value * 1024`)을 바꾸는 변이 → 지금 merge 게이트 어디서도 실패하지 않음. 옮긴 뒤 FE-GATE-005에서 실패 | + +### T-08 [w2-fe-2 관련: 시험 timeout] 새 timeout 규칙 밖에 손으로 정한 숫자 54곳과 옛 상수 4벌이 남았고, taxonomy가 옛 방식을 예로 든다 + +| 칸 | 내용 | +|---|---| +| 성격 | 확인된 결함(문서와 코드가 다름, 갈라진 사본) | +| 관련 관점 | 9, 23, 10 | +| 심각도·우선순위 | Low · P3 | +| 통제 | M3(기본 timeout + 자식 프로세스는 `tests/setup.ts`가 막음) / 숫자의 근거는 M1 | +| 증거 | E1 | +| 근거 | `docs/work/reference/testing.md` 2절은 "값은 desktop에서 잰 가장 긴 실행으로 정한다: `childProcessTimeout()`"라 적는다. `91962e24` 본문은 "시험마다 손으로 정한 숫자"를 근거가 없다고 버렸다. 그러나 기본값이 아니라서 가드에 걸리지 않는 손 숫자가 54곳 남았다(`git grep -nE "\}, [0-9]{2,3}_000\);\|\{ timeout: [0-9]{2,3}_000 \}" -- 'tests/**/*.test.ts' 'tests/**/*.test.tsx'`, 예: `tests/unit/test-evidence-source-rules.test.ts:38`, `tests/system/ci-runner/ci-artifact-contract.test.ts` 16곳). `PROCESS_HEAVY_TIMEOUT_MS = 30_000`이 네 파일에 따로 있다(`tests/unit/risk-coverage.test.ts:34`, `tests/unit/security-followup-fixture.ts:26`, `tests/integration/provider-guardian-transaction.test.ts:28`, `tests/system/ci-runner/ci-artifact-contract.test.ts:65`). `docs/testing/taxonomy.md:104-106`은 여전히 `PROCESS_HEAVY_TIMEOUT_MS`를 예로 든다 | +| 발생 조건 | 새 시험 작성자가 taxonomy를 따라 상수를 복사할 때 | +| 영향 | 같은 문제(부하 desktop의 자식 프로세스 시험)에 두 규칙이 있고, 한쪽은 근거가 남지 않는다 | +| 최소 개선 방향 | 54곳과 상수 4벌을 `childProcessTimeout(<잰 ms>)`로 바꾸거나, 이미 잰 값이면 그 값을 인자로 적는다. taxonomy 예시를 helper로 고친다 | +| 완료 기준 | 자식 프로세스 시험의 timeout이 모두 helper를 거친다. taxonomy와 testing.md가 같은 방법을 적는다 | +| RED 시험 아이디어 | 해당 없음(규칙 통일). 원하면 `tests/setup.ts` 가드를 "helper가 만든 값이 아닌 timeout"까지 넓히는 시험 | + +### T-09 생성 기능 e2e의 오류 응답이 "짝 백엔드의 Envelope"라는 주석과 다르다 + +| 칸 | 내용 | +|---|---| +| 성격 | 구조적 위험(대역이 실제 상대와 다름, 결함 패턴 T6). 지금은 판정이 status로만 정해져 결과가 같다 | +| 관련 관점 | 17, 10 | +| 심각도·우선순위 | Low · P3 | +| 통제 | M1 | +| 증거 | E1 | +| 근거 | 주석: "The API answers are the paired backend's Envelope"(`tests/e2e/generated-feature.spec.ts:26-27`). 429 답은 `code: "RATE_LIMITED"`, `category: "SYSTEM"`(`:62-68`, `:246`)이다. 짝 백엔드는 `RATE_LIMIT_EXCEEDED`, `category: RATE_LIMIT`, `Retry-After`다(백엔드 `docs/registries/error-codes.yaml:371-375`, `docs/web/runbook.md:8`). 500 답은 `INTERNAL_ERROR` + `SYSTEM`(`:284`)인데 백엔드는 `category: INTERNAL`이다(`error-codes.yaml:835-838`). 프론트의 429 판정은 status로만 한다(`src/contracts/errors.ts:326`, `src/adapters/http/http-execution-v3.ts:1300-1309`). 쓰기 전 거절 표는 code로 본다(`src/adapters/http/backend-envelope.ts:168-193`) | +| 발생 조건 | 프론트가 429·500의 code나 category를 읽게 되는 변경(예: 429 code별 안내) | +| 영향 | 브라우저 흐름이 존재하지 않는 code로 통과한다 | +| 최소 개선 방향 | `failure()` 두 호출을 백엔드 표의 code·category로 바꾼다. 가능하면 `config/contracts/`의 짝 계약 사본에서 읽는다 | +| 완료 기준 | e2e의 오류 Envelope가 짝 백엔드 registry 행과 같다 | +| RED 시험 아이디어 | 해당 없음(대역 교정) | + +### T-10 `@a11y` 브라우저 시험을 merge가 두 번 돈다 + +| 칸 | 내용 | +|---|---| +| 성격 | 개선 제안(실행 비용). 1101/10-06(빠른 층, 결정 대기)과 같은 모양의 브라우저 층 자리 | +| 관련 관점 | 14, 20 | +| 심각도·우선순위 | Low · P3 | +| 통제 | 해당 없음 | +| 증거 | E1 + 이번 실행 시간(FE-GATE-009 32 s, desktop, summary.txt) | +| 근거 | FE-GATE-008의 `test:e2e`는 `playwright test` 전체다(`package.json:43`). FE-GATE-009의 `test:a11y`는 `--grep @a11y`를 다시 돈다(`package.json:58`). `@a11y` 시험은 `tests/e2e/accessibility.spec.ts`와 `tests/e2e/generated-feature.spec.ts:351-370`이다. 009는 webServer 빌드를 한 번 더 하고, 생성 기능 spec의 `beforeAll` 사본 빌드도 다시 돈다. `docs/work/reference/testing.md` 6절은 "merge 단계가 같은 파일을 두 번 돌리지 않는지 본다"고 적는다 | +| 최소 개선 방향 | `test:e2e`에 `--grep-invert @a11y`를 주고 접근성은 009 하나에서만 센다. 또는 두 번 도는 이유를 1101/10-06 결정에 같이 적는다 | +| 완료 기준 | 한 merge에서 `@a11y` 시험이 엔진마다 한 번 돈다 | +| RED 시험 아이디어 | 해당 없음 | + +### 개선 제안 묶음 (GWT와 작은 것) + +| 무엇 | 건수 | 대표 위치 | +|---|---|---| +| 이름이 본문에 없는 동작을 말한다 | 1 | `tests/storybook/galleries.spec.ts:74` "duplicate toast" — 토스트를 한 번만 띄운다. 중복 처리는 `tests/component/design-system-platform.test.tsx:216`이 본다 | +| 한 시험이 독립된 행동 여럿을 섞어 실패 위치가 흐리다 | e2e·capability 7곳 이상 | `tests/e2e/theme.spec.ts:4`(axe 스캔 + 저장 유지), `tests/storybook/galleries.spec.ts:74`(메뉴·토스트·탭), `tests/browser-capabilities/indexeddb-runtime.spec.ts:256`, `opfs-runtime.spec.ts:3`, `public-cache-storage.spec.ts:3`, `browser-files.spec.ts:14` | +| 이름에 여러 경우를 쉼표·and/or로 나열(한 시험에 여러 입력) | Vitest·Playwright 이름 137개(전체 `it/test` 약 2,820 + e2e 56 중, 휴리스틱) | `tests/unit/docs-system.test.ts:181`, `tests/unit/repository-layout.test.ts:59`. `it.each`로 나누면 실패한 경우가 이름에 나온다 | +| 부재 단언을 고정 대기로 한다(신호 없음) | 5 | `tests/e2e/app-shell.spec.ts:65`(300 ms), `tests/browser-capabilities/cross-context-invalidation.spec.ts:201`, `:270`(100 ms), `opfs-runtime.spec.ts:413`, `:512`(250 ms). 부하에서 늦게 온 사건은 통과 쪽으로 빠진다. 뒤에 보낸 표지 메시지를 기다린 뒤 "앞 메시지가 없다"를 단언하는 식으로 바꾼다 | +| 콘솔 warning 무시가 부분 문자열이다 | 1 | `tests/support/browser/strict-browser-test.ts:22` `includes("NO_COLOR")`. 출처 주석이 없다. WebKit 문구처럼 정확 일치로 좁히거나 출처를 적는다 | + +## 3. 넘길 것 + +- → fe-a11y: T-01에서 "꼭 필요하지 않은 움직임"의 범위(스피너는 멈춰야 하나, 회전만 줄이나)와 M7 수동 기록 문구(`docs/accessibility/route-reviews/APP_HOME.md:18`)가 맞는지. 시험 검출력은 이 렌즈 몫, 정책 내용은 그쪽 몫이다. +- → fe-structure(또는 게이트 담당): T-04의 ESLint 규칙 범위와 예외 두 파일. +- → 총괄(게이트 결정): T-07의 남은 다섯 scale 파일을 pr tier로 옮길지, 사유만 고칠지. T-10은 1101/10-06 결정 대기에 같이 붙일지. +- → 백엔드 repo 세션(총괄 경유): 해당 없음. T-09는 백엔드 registry를 읽기만 했고 프론트 쪽 교정이다. +- → 결정 대기 D11(생성 기능 설치 상태의 브라우저 merge 게이트): 참조 기능 삭제(`e3c8db48`) 뒤 템플릿에는 `session-required` 라우트가 없다. 그래서 `tests/e2e/accessibility.spec.ts:48-88`의 보호 라우트 분기와 `notChecked` 기록은 템플릿 게이트에서 한 번도 돌지 않는다. 로직은 `tests/unit/a11y-report.test.ts:110-197`이 fixture descriptor로 본다. D11이 정할 일이라 새 발견으로 세지 않았다. + +## 4. 실험 요청 + +모두 desktop, 한 checkout에서 하나씩, 실험마다 작업 폴더를 되돌린다. 브라우저 실행은 실행마다 다른 `TEST_RUN_ID`. + +| ID | 목적 | 변이 패치 | 명령 | env | 상한 | 기대(지금 코드가 맞다면) | +|---|---|---|---|---|---|---| +| E-01 | T-01 확인 | `src/presentation/styles/theme/responsive.css`에서 86~95줄(`@media (prefers-reduced-motion: reduce) { … }`)을 지운다 | `scripts/verify.sh exec -- corepack pnpm exec playwright test tests/e2e/accessibility.spec.ts -g "reduced-motion"` | `TEST_RUN_ID=r9-l3-e01` | 15분 | 세 엔진 모두 **통과**(= 거짓 통과 확인) | +| E-02 | T-02 확인 | `tests/browser-capabilities/opfs-runtime.spec.ts:352`와 `:470`의 `if (!(await installOpfsTab(page, scope))) return;`을 `expect(await installOpfsTab(page, scope), "OPFS supported").toBe(true);`로 바꾼다 | `scripts/verify.sh exec -- corepack pnpm exec playwright test --config playwright.capabilities.config.ts tests/browser-capabilities/opfs-runtime.spec.ts` | `TEST_RUN_ID=r9-l3-e02` | 10분 | 실패하는 엔진이 있으면 그 엔진은 지금 단언 없이 통과 중이다. 엔진별 결과를 적는다 | +| E-03 | T-03 확인 | `scripts/check-test-evidence.ts:307-311`(`wholeUiMask` 블록)을 지운다 | ① `scripts/verify.sh exec -- node scripts/run-vitest.ts run tests/unit/test-evidence-source-rules.test.ts` ② `scripts/verify.sh exec -- sh -c 'corepack pnpm check:test-evidence:fixture; echo rc=$?'` | 없음 | 5분 | ① 4건 통과, ② rc=1이고 "Test evidence failed:" 출력(= FE-GATE-029 기대도 그대로 충족). 변이가 살아남는다 | +| E-04 | T-06 축소 확인 | `tests/e2e/old-tab-chunk-recovery.spec.ts:195`의 `...(await preloadedWith(builds.dist.a, pageSource(aManifest, PLATFORM))),` 줄을 지운다 | `scripts/verify.sh exec -- corepack pnpm exec playwright test tests/e2e/old-tab-chunk-recovery.spec.ts --repeat-each=5` | `TEST_RUN_ID=r9-l3-e04` | 25분 | 세 엔진 15/15 통과 | +| E-05 | 게이트 연결 현재 상태 | 없음 | `scripts/verify.sh script check:ci:gating` | 없음 | 5분 | PASS(목록 밖 시험 0, stale 항목 0). 노트북에서 스크립트 경로 대조로는 377파일 모두 어떤 스크립트에 있다 | + +## 5. 결함 아님으로 판정한 의심 + +- **W1의 "preload-use.ts가 쓰이지 않는 preload를 검사하지 않고 WebKit 추정 경고만 받아들인다"**: 템플릿에는 사실이 아니다. 미실행 preload를 `preloadunused:`로 실패시킨다(`tests/support/browser/preload-use.ts:190-202`). WebKit 문구는 앵커가 있는 정규식 하나로만 무시한다(`strict-browser-test.ts:16-24`). 변이 시험(`tests/e2e/preload-use.spec.ts:111-120`, `:247-260`)과 문구 경계 시험(`:262-296`), 판정 시험(`:302-310`)이 있다. tech-log main에는 이 파일이 없다. +- **route를 직접 fulfill하는 시험이 preload 검사를 덮는가**: 아니다. build script를 fulfill하는 것은 `production-csp.spec.ts:30-41` 하나이고 `fulfillBuildScript`를 쓴다. 생성 기능·접근성 spec은 API origin만 가로챈다. 지연 시험은 `route.fallback()`으로 추적기에 넘긴다(`preload-use.spec.ts:192-198`). `preloadunused` 허용을 쓰는 두 spec(boot 실패, old-tab)은 route가 아니라 빌드 서버 전환으로 실패를 만든다. +- **SW가 제어하는 문서에서 preload 검사가 빠진다**: 빠지는 것은 맞다. 이름 붙여 실패(`preload-use.ts:198-199`)하고 SW update spec만 허용한다(`service-worker-update.spec.ts:50-52`). 1105 리뷰가 결함 아님으로 판정했고, 결과 단언 시험이 더해졌다(`:302-350`, 1105/06-03 고쳐짐). +- **boot 실패 spec이 boot graph 전체를 `preloadunused`로 허용**: 일으킨 실패(모듈 평가 중 throw)의 직접 효과이고 엔진마다 멈추는 위치가 달라 전체가 맞다(`boot-module-failure.spec.ts:47-69`). +- **`chunk-load-error.spec.ts`의 맨 test**: 일부러 404 import를 내는 분류 시험이고 지난 리뷰들이 이유를 받아들였다. 남는 위험은 T-04에 적었다. +- **`vi.fn()` fetcher**: 모두 "보내지 않았다"를 단언하는 감시용이다(`tests/integration/fileserver-upload.test.ts:653-661`, `http-execution-v3-auth-profile.test.ts:110-136` 등). 네트워크 동작은 MSW strict 서버(`tests/mocks/server.ts:9`)로 본다. +- **e2e webServer가 CI 빌드 env를 물려받음**(`playwright.config.ts:36-42`): FE-GATE-008이 증거로 쓰는 job 자신의 빌드라 의도다. 사본 빌드는 `localBuildEnvironment()`를 쓴다(`tests/e2e/support/fixture-builds.ts:57`). +- **`tests/setup.ts`의 자식 프로세스 가드** [w2-fe-2 파일]: 기본 timeout 값을 `vitest.config.ts`와 맞추는 시험이 있고(`tests/unit/child-process-timeout.test.ts:20-22`), 가드를 끄면 실패하는 시험이 있다(`:13-18`). hook 미검사는 주석과 커밋에 적힌 한계다. +- **참조 기능 시험 삭제로 플랫폼 검사를 잃었는가(T10)**: 표본 9개 모두 대응 시험이 있다. sign-out 판정 `tests/unit/runtime-adapters-auth-profile.test.ts:364-420`, intent 비노출 `tests/unit/http-execution-v3.test.ts:426-441`, 중복 제거·retry 겹침 `tests/platform/traffic/request-deduplication.test.ts`, fan-out `tests/platform/traffic/request-fanout.test.ts`. 전수 대조는 1절 「확인 못 한 것」. +- **위험 커버리지 행 삭제**(`config/testing/risk-coverage.json`): 지운 기능 파일의 행만 지웠다(`e3c8db48`). 기준을 낮춘 것이 아니다. +- **새 mutation admission 시험**(`tests/component/application-mutation-admission.test.tsx:619-942`): 같은 키 유지, 거절 종류별 판정, 보내기 전 실패를 키 순서까지 단언한다. 행동이 여럿이지만 한 흐름(제출 → 재전송 → 다음 제출)의 전이를 보는 시험이라 GWT 결함이 아니다. +- **visual 시험이 기능 영역을 가림**: 1103 결정 D3(기능 영역을 가리고 찍음)대로다. +- **0929/12-06(Vitest 폴더의 `*.spec.ts`를 게이트 안으로 셈)·0929/12-07(예외 목록에 담당 없음)·1101/10-05·10-06·10-08**: 1106에서 「남김」 또는 결정 대기로 정해졌다. 지금 코드도 그대로다(`scripts/lib/ungated-tests.ts:18`, `:94-95`). 다시 세지 않았다. diff --git a/docs/reviews/2026-11-round9-04-ux-design-system.md b/docs/reviews/2026-11-round9-04-ux-design-system.md new file mode 100644 index 00000000..7cf9acaf --- /dev/null +++ b/docs/reviews/2026-11-round9-04-ux-design-system.md @@ -0,0 +1,435 @@ +# round9 L4 — UX·디자인 시스템 (렌즈 fe-ux, fe-design-system) + +> round9 리뷰(2026-11-12, 대상 main `5250ff95`)의 영역 기록이다. 서브에이전트가 쓴 원문을 그대로 옮겼다. 바꾼 것은 이 인용 블록과, 작업 폴더 절대 경로를 `(작업 폴더)`로 줄인 것뿐이다. 발견 ID는 이 파일의 이름표(R-01 등)이고, 라운드 ID(`1112/NN-MM`)와의 대응은 [README](2026-11-round9-review.md) 15절이다. + + +대상: `5250ff95`(tree `75cc3752`). 전체 리뷰. 읽기만 했다. repo 파일은 고치지 않았다. + +## 0. 결론 + +- 판정: **고칠 것 있음.** 새 발견 17건. Critical 0 · High 0 · Medium 2 · Low 15. 우선순위는 P2 8, P3 9다. 성격은 확인된 결함 15, 미검증 1(DS-04, 실험 X-02로 확인), 구조적 위험 1(DS-07)이다. +- Medium 두 건은 둘 다 "게이트가 통과해도 보지 않는 곳"이다. + - DS-01: 셸·페이지 템플릿·카드 CSS가 간격·층·그림자·반경 토큰을 건너뛰고 날 값을 쓴다. 그래서 토큰을 바꿔도 밀도가 바뀌지 않는다. `src/presentation/AGENTS.md`의 "토큰 밖 색·간격을 쓰지 않는다"와 PRODUCT 원칙 3을 어긴다. + - DS-02: 갤러리를 Storybook으로 옮기면서 두 갤러리의 전체 화면 axe 검사가 사라졌다. VD-08 결정 3을 어기고, 결함 패턴 T10에 해당한다. +- 화면 쪽 Low 가운데 사용자에게 바로 보이는 것은 둘이다. + - UX-01: 생성 기능은 모두 `session-required`다. 그래서 로그인 전 최종 사용자에게 "이 화면은 인증 연동 지점을 확인하기 위한 보호 라우트입니다."가 보인다. + - UX-02: 같은 키 재전송이 429·503 `RATE_LIMIT_*`로 거절되면(1106/03-01 수정이 만든 길) "입력 내용을 확인해 주세요." 제목 아래에 나온다. 409 충돌도 같다. 0925/08-01의 완료 기준 문장이 재전송 경로에서 다시 깨진다. +- 이월: 0929/08-01은 **남음**이다. 셸 언어 선택지에 `Pseudo`·`RTL smoke`가 그대로 있다(`src/presentation/layouts/app-shell.tsx:82-87`, `src/presentation/i18n/message-contract.ts:8-13`). 새로 세지 않는다. + +## 1. 범위 + +**읽은 경로** + +- `src/presentation/{templates,components,forms,i18n,pages,layouts,design-system(index·primitives 전부·patterns·icons·tokens·stories 2개),styles(theme.css, theme/*.css 6개)}` +- 상태 화면 문구 확인을 위해 `src/presentation/routes/app-router.tsx:81-310`과 `src/presentation/providers/session-provider.tsx:78-107` +- `examples/platform-overview-page.tsx`는 import와 PageHeader 사용만 봤다. 이 화면의 위치는 결정 대기 D2다. +- `.storybook/main.ts`, `.storybook/preview.tsx` +- `tests/storybook/*.spec.ts`, `tests/visual/*.spec.ts`, `playwright.visual.config.ts`, `playwright.storybook.config.ts` +- 골든 PNG는 이름과 갱신 커밋만 봤다(5장. 바뀐 3장은 `7625dc45`·`c7e80f2f`). +- `docs/styling/design-tokens.md`, `docs/manual/02-decision-tables.md` 4·6절, `docs/manual/reference/{global-ids,patterns}.md`(필요한 절) +- 설계서 세 개의 필요한 절: design-system-platform 1·8·9·10·11·12·13절, routing 6·7·11·12절, data-flow 7.2·8절 +- 생성 화면 템플릿: `scripts/create-feature.ts`의 `renderMessageCatalog`·`renderListPage`, `scripts/create-feature-write-slice.ts`의 `renderWriteMessages`·`renderDetailPage`·`renderCreatePage` +- 기준과 근거: `scripts/check-design-system.ts`, `scripts/lib/design-system-rules.ts`, `scripts/check-i18n.ts`, `.dependency-cruiser.json`의 디자인 시스템 규칙, `PRODUCT.md`, ADR VD-08, `CHANGELOG.md` 알려진 제한 +- 지난 리뷰: 1106 `08-presentation.md`(이월 확인), 1101 `08-presentation.md` 휴리스틱 표, `2026-11-01-ui-design-audit.md` +- `bbde570`과의 차이: `git diff --stat bbde570 5250ff95`로 바뀐 45파일을 먼저 봤다. 그중 `use-app-form.ts`, `catalog.ts`, `component.css`, `base.css`, `primitives.css`, `galleries.stories.tsx`, `preview.tsx`, `tests/visual/*`, `tests/storybook/galleries.spec.ts`는 줄 단위로 봤다. + +**쓴 스킬과 그 기준으로 본 것** + +- `fe-ux` + - 함정 1(템플릿 선택) → UX-06 + - 함정 2(disabled 대신 pending) → UX-05 + - 함정 5·6(서버 원문, 문자열 조립) → UX-07, 5절 + - 함정 8(결과 불명 화면) → DS-03 + - 함정 11(예제와 최종 사용자 화면을 섞음) → UX-01 + - 체크리스트 "loading이 내용 모양을 따른다" → UX-04 + - 체크리스트 "날짜·숫자·목록은 formatter" → UX-03 + - 체크리스트 "409를 검증 오류로 위장하지 않는다" → UX-02 + - 체크리스트 "h1 = catalog 제목" → UX-07 +- `fe-design-system` + - 함정 1(검사가 날 px를 안 본다) → DS-01 + - 함정 3(color-mix) → DS-08 + - 함정 7(API를 열어 둔다) → DS-07 + - 함정 10(골든 허용치) → DS-04 + - 함정 11(갤러리 story만 골든에 든다) → DS-03 + - 체크리스트 "새 component 토큰은 contract에" → DS-05 + - 체크리스트 "primitive→semantic 파생" → DS-06 + - 체크리스트 "필수 story" → DS-03 + - 체크리스트 아이콘 토큰 이름 → DS-08 + +**실행 결과(읽기만)** + +- desktop `/tmp/claude-gates/r9fe-base/summary.txt`를 읽었다. tree `75cc3752`(HEAD tree와 같음)에서 다음이 rc=0이다. + - FE-GATE-006(component) + - FE-GATE-008(e2e·storybook·visual) + - FE-GATE-010(`check:design-system`·`check:i18n`·architecture) + - FE-GATE-011(story build) +- FE-GATE-013은 rc=1이다(결정 D8, 이 영역 판정에 쓰지 않음). +- 게이트 로그는 두 줄 요약이라 시험별 결과는 읽지 못했다. `snapshot/`은 아직 없다. +- 아래 발견은 "게이트가 통과하는데 보지 않는 것"이라 이 결과와 모순되지 않는다. + +**확인 못 한 것(화면을 띄워야 아는 것)** + +- 다크 테마에서 modal 가림막이 밝은 색으로 깔리는지. `--dialog-backdrop`이 다크에서 밝은 `--color-content` 55%다(`component.css:168-172`). + - 열어 볼 곳: Storybook `platform-design-system--overlay-interaction`의 dark, 또는 `/` 390px dark에서 메뉴 drawer를 연다. +- UX-05의 포커스 유실을 세 엔진에서 실제로 보는 것. + - 열어 볼 곳: 생성 기능의 목록 라우트를 로그인 전에 열고, "로그인 시작"을 누른 뒤 sign-in이 실패하는 경우. +- UX-02를 생성 기능 화면에서 실제로 보는 것. + - 열어 볼 곳: `--with-create --keyed` 작성 라우트에서 첫 저장의 응답을 잃게 하고, 재전송에 503 `RATE_LIMIT_UNAVAILABLE`을 준다. +- en-XA·320px에서 StatusPage, ErrorSummary, 긴 FormFailureStatus의 배치. 갤러리와 골든에 없다(DS-03). +- RTL에서 Pagination 아이콘 방향과 Switch thumb 위치. 코드에는 있다. + +## 2. 발견 + +### UX-01 상태 화면 문구가 템플릿 개발자용이고, 행동을 말하면서 행동 버튼이 없다 + +| 칸 | 내용 | +| --- | --- | +| 성격 · 관점 | 확인된 결함 · 24, 28, 3, 23 | +| 심각도·우선순위 · 통제 · 증거 | Low · P2 · M0(문구를 보는 검사 없음) · E1 | +| 근거 | `src/presentation/i18n/catalog.ts`의 문구 셋이 구현 설명이다. :88-89 `route.auth.required.description` "이 화면은 인증 연동 지점을 확인하기 위한 보호 라우트입니다."(en :294-295 "…demonstrates the authentication integration seam"), :82-83 `route.auth.integration.description` "외부 인증 소유자가 연결되면…", :78-79 `route.disabledFeature.description` "…코드에는 포함되어 있으며 운영자가 다시 켤 수 있습니다."
`app-router.tsx:130-165`: 잘못된 주소·끈 기능 화면은 "안전한 탐색 링크를 사용해 주세요." 같은 `

`만 있고 `primaryAction`이 없다. 같은 템플릿의 `not-found-page.tsx:12-17`은 "홈으로 이동" 링크를 준다. `:262-271` integration-failed 화면도 행동이 없다.
생성 기능은 `access: "session-required"`다(`scripts/create-feature.ts:578`, `scripts/create-feature-write-slice.ts:130`). | +| 발생 조건 | 파생 서비스에서 로그인 전 사용자가 생성 기능 라우트를 열 때. 운영자가 기능을 끄거나 주소가 틀렸을 때 | +| 영향 | 최종 사용자가 개발용 설명을 읽는다. 끈 기능과 잘못된 주소 화면에서는 다음 행동 버튼이 없다. 이 catalog는 템플릿 소유 파일이라 제품이 고치려면 템플릿 파일을 고쳐야 한다(결함 패턴 S4). 모든 파생 서비스에 복제된다 | +| 약속 | `PRODUCT.md` 원칙 1(디자인 시스템은 최종 사용자용, 예제는 개발자용, 섞지 않는다), fe-ux 함정 11, 체크리스트 "오류는 무엇이 틀렸고 어떻게 고치는지 쓴다", routing 설계 7.5절 "각 변형은 … 안전한 primary/secondary action" | +| 최소 개선 방향 | 세 묶음 문구를 최종 사용자 말로 바꾼다(예: "이 화면을 보려면 로그인해 주세요.", "지금은 로그인할 수 없습니다. 잠시 후 다시 시도해 주세요."). 운영 설명은 진단으로 보낸다. `InvalidRouteSurface`·`DisabledFeatureSurface`·integration 화면에 `NotFoundPage`처럼 홈 링크 `primaryAction`을 준다 | +| 완료 기준 | 이 키들의 ko·en 문구에 "라우트·연동 지점·seam·코드에는 포함·운영자"가 없다. 세 화면에 링크 행동이 하나씩 있다 | +| RED 시험 | `tests/component/route-status-surfaces.test.tsx`: `invalid-route`·`disabled-feature`·`auth-integration-required` 표면에 `getByRole("link", { name: KO_MESSAGES["action.goHome"] })`가 있다. 지금 실패하고, 고치면 통과한다 | + +### UX-02 입력과 무관한 저장 실패가 ErrorSummary "입력 내용을 확인해 주세요." 아래에 나온다 + +| 칸 | 내용 | +| --- | --- | +| 성격 · 관점 | 확인된 결함(일부는 수정이 만든 결함, 결함 패턴 G13) · 6, 28, 24, 23 | +| 심각도·우선순위 · 통제 · 증거 | Low · P2 · M1 · E1 | +| 근거 | `src/presentation/forms/use-app-form.ts:432-437`: 같은 키 재전송이 쓰기 전에 거절되면 `setFormErrors(["form.resendLater"])`. 1106/03-01 수정 `25685871`이 넣었다.
`:313-317`: 선언한 409 `CONFLICT`가 `setFormErrors(["form.conflict"])`.
생성 작성 페이지가 `form.formErrors`를 `ErrorSummary`에 넘긴다(`scripts/create-feature-write-slice.ts:698-705`).
`ErrorSummary`는 `role="alert"`이고 제목이 항상 `form.errorSummary` "입력 내용을 확인해 주세요."다(`src/presentation/forms/form-components.tsx:56-62`).
같은 순간 feedback 자리에는 결과 불명 `AsyncSurface`가 있다. 시험 `tests/component/form-foundation.test.tsx:1190-1196`은 `form-errors` testid의 글자만 보고, 어느 표면에 나오는지는 보지 않는다 | +| 발생 조건 | (a) KEYED 쓰기의 응답을 잃은 뒤 "같은 요청으로 다시 보내기"가 429·503 `RATE_LIMIT_*`를 받을 때. (b) `refusedBeforeWrite`에 적고 `refusalMessages`에 적지 않은 409(`02-decision-tables.md:188`이 이 동작을 안내한다) | +| 영향 | (a)에서는 저장 버튼이 꺼져 있는데 "입력 내용을 확인"하라고 해서 사용자가 입력을 고치려 한다. 알림도 둘(alert + status)이 함께 나온다. 0925/08-01의 완료 기준 "'입력 내용을 확인해 주세요' 제목은 나오지 않는다"(429)가 재전송 경로에서 다시 깨진다 | +| 약속 | data-flow 설계 8절 필수 동작 5("409는 validation error로 위장하지 않음")와 5a("401·403·429 같은 입력 외 실패는 ErrorSummary가 아니라 FormFailureStatus"), `form-contracts.ts:21` 주석, fe-ux 체크리스트 | +| 최소 개선 방향 | `formErrors`는 입력 오류만 담는다. 재전송 거절 안내는 feedback 자리로 보낸다(결과 불명 `AsyncSurface`의 설명, 또는 `FormFailureStatus`). 충돌은 `form.result === "conflict"`일 때 feedback에 충돌 문구와 행동을 둔다. 결정 D10(결과 불명과 키를 지킨다)은 그대로다. 바꾸는 것은 표면뿐이다 | +| 완료 기준 | 두 경로에서 `form.errorSummary` 제목이 없다. 안내 문구는 feedback 자리에 있고 포커스가 그곳으로 간다 | +| RED 시험 | `form-foundation.test.tsx` 1155행 시험의 harness가 실제 `ErrorSummary`와 `FormPage feedbackId`를 그리게 한다. 재전송 거절 뒤 `queryByRole("heading", { name: KO_MESSAGES["form.errorSummary"] })`가 `null`인지 단언한다. 409 선언 경로도 같다. 지금 실패한다 | + +### UX-03 숫자를 locale formatter 없이 그린다 + +| 칸 | 내용 | +| --- | --- | +| 성격 · 관점 | 확인된 결함 · 23, 1 | +| 심각도·우선순위 · 통제 · 증거 | Low · P3 · M0 · E1 | +| 근거 | 생성 목록 문구 "총 {count}개 항목" / "Total items: {count}"에 `query.data.total`을 그대로 넣는다(`scripts/create-feature.ts:856`, `:864`, `:1203-1204`). `resolveMessage`는 `String(value)`만 한다(`message-contract.ts:115-118`).
`TextArea` 남은 글자 수가 en에서 단수형이 없다("1 characters remaining", `catalog.ts:365`, `text-area.tsx:66-71`).
`ProgressBar`가 `{Math.round(...)}%`를 글자로 붙인다(`progress-bar.tsx:13`).
`useLocale()`의 `number()`·`plural()`(`locale-provider.tsx:104-110`)을 쓰는 화면 코드가 0곳이다(`git grep`) | +| 발생 조건 | 목록 항목이 1,000개 이상일 때, en에서 남은 글자가 1일 때 | +| 영향 | "총 12345개 항목"이 되고, 영어 문법이 틀린다. 생성 뼈대라 모든 기능에 복제된다 | +| 약속 | fe-ux 체크리스트 "날짜·숫자·목록은 locale formatter", design-system-platform 12절 국제화, 9절 plural/select | +| 최소 개선 방향 | 생성 목록은 `{ count: number(query.data.total) }`. 이 키의 값 타입을 string으로 받게 한다. `TextArea`는 `plural`로 단수·복수를 고른다. `ProgressBar`는 `number(value / max, { style: "percent" })` | +| 완료 기준 | 생성 목록이 1,234를 "1,234"로 보인다. en 남은 1자가 단수형이다 | +| RED 시험 | 생성 페이지 시험(`renderPageTest`)에 total 12345 시나리오를 넣고 "총 12,345개 항목"을 기대한다. `TextArea`는 en-US, `maxLength=5`, 값 4자에서 "1 character remaining"을 기대한다. 둘 다 지금 실패한다. ProgressBar는 ko·en에서 결과가 같아 RED가 없다 | + +### UX-04 라우트 `loadingSurface`가 로딩 모양을 고르지 않는다 + +| 칸 | 내용 | +| --- | --- | +| 성격 · 관점 | 확인된 결함 · 22, 9, 4 | +| 심각도·우선순위 · 통제 · 증거 | Low · P3 · M0 · E1 | +| 근거 | `app-router.tsx:81-97`: `loadingSurface`는 `data-surface` 속성으로만 쓰인다. 모든 라우트가 같은 `LoadingSurface`(블록 하나 `.ui-skeleton` h-24, `primitives.css:125-127`)를 그린다. `AsyncSurface`의 `initial-loading`도 같다(`async-surface.tsx:161`).
매뉴얼은 이 값을 "로딩 화면 이름"으로 정하라고 한다(`docs/manual/01-add-a-feature.md:438`). 생성 명령은 `"-list"`를 넣는다(`create-feature.ts:579`) | +| 영향 | 기능 작성자가 효과 없는 값을 정한다. 목록·상세·폼의 첫 로딩이 내용과 다른 모양이라 로딩이 끝날 때 배치가 크게 바뀐다 | +| 약속 | fe-ux 체크리스트 "loading surface가 실제 내용 모양(collection·detail·form)을 따른다", routing 설계 6.1절, 12절 "route metadata가 loading … 행동에 실제 연결된다" | +| 최소 개선 방향 | 권하는 안: `LoadingSurface`에 `shape: "page" \| "collection" \| "detail" \| "form"`(닫힌 union) prop을 둔다. 라우트 `loadingSurface`를 그 union으로 좁혀 `RouteLoadingSurface`가 고르게 하고, 생성 명령은 `collection`을 넣는다. 다른 안: 매뉴얼을 "진단 이름일 뿐 모양은 같다"로 고치고 렌즈 체크리스트에서 빼는 것. 이 안은 소유자 결정이 필요하다 | +| 완료 기준 | `collection`과 `form` 로딩의 DOM 구조가 다르다. 매뉴얼 문장과 동작이 같다 | +| RED 시험 | component 시험에서 `loadingSurface`가 다른 두 라우트의 로딩 표면이 서로 다른 skeleton 구조인지 단언한다. 지금 실패한다 | + +### UX-05 진행 중 버튼을 `disabled`로 끄는 길이 템플릿 API에 남았다 + +| 칸 | 내용 | +| --- | --- | +| 성격 · 관점 | 확인된 결함 · 28, 22, 23 | +| 심각도·우선순위 · 통제 · 증거 | Low · P3 · M1 · E1(포커스 유실은 미검증, fe-a11y로 넘김) | +| 근거 | `PageActionDefinition` 버튼에는 `disabled`만 있고 `pending`이 없다(`src/presentation/templates/page-templates.tsx:18-31`, `:285-292`).
그래서 StatusPage의 로그인·복구 버튼은 진행 중 `disabled: pending`과 "처리 중…"으로 바뀐다(`app-router.tsx:289-297`). 셸 헤더 세션 버튼도 같다(`app-shell.tsx:95-111`).
`useSessionAction().run`은 진행 중 중복 실행을 막지 않고 `disabled`에 기댄다(`session-provider.tsx:92-107`) | +| 발생 조건 | 키보드로 "로그인 시작"을 누르고 sign-in이 실패할 때 | +| 영향 | 실패 알림(`shell.session.actionFailed`)이 뜰 때 포커스는 이미 body에 있다. 실패 뒤 다음 행동을 잃는 결함 패턴 C11이다 | +| 약속 | fe-ux 함정 2, `docs/manual/02-decision-tables.md` 6절("꺼진 버튼은 키보드 포커스를 잃는다") | +| 최소 개선 방향 | `PageActionDefinition` 버튼에 `pending`·`pendingLabel`을 더해 `Button`으로 넘긴다. `run`이 진행 중이면 무시하게 한다(또는 pending인 `Button`이 활성화를 삼키게 한다). 라우터와 셸이 `pending`을 쓴다 | +| 완료 기준 | 진행 중에 버튼이 `disabled`가 아니고 `aria-busy="true"`다. 실패 뒤 포커스가 그 버튼에 있다 | +| RED 시험 | `route-status-surfaces.test.tsx`에서 `beginSignIn`이 미해결인 동안 `expect(button).not.toBeDisabled()`와 `aria-busy` 단언. 지금 실패한다 | + +### UX-06 홈이 페이지 템플릿과 `LinkButton`을 건너뛴다 + +| 칸 | 내용 | +| --- | --- | +| 성격 · 관점 | 확인된 결함 · 23, 4 | +| 심각도·우선순위 · 통제 · 증거 | Low · P3 · M0 · E1 | +| 근거 | `src/presentation/pages/home-page.tsx:50-55`: 템플릿 대신 자기 `section.ui-page`와 `PageHeader`를 쓴다. `:82-92`: ``로 `LinkButton`(`link-button.tsx:25-51`, `index.ts:17-21`에서 공개)을 손으로 다시 만든다 | +| 영향 | `PRODUCT.md`는 홈이 파생 서비스에 남는다고 적는다. 그래서 그대로 복제되고, 개발자가 따라 하는 예가 된다. `LinkButton`의 variant·size가 바뀌면 홈만 어긋난다 | +| 약속 | fe-ux 체크리스트 "페이지는 다섯 템플릿 중 하나", brief의 "primitive를 우회한 날 스타일" | +| 최소 개선 방향 | `StandardPage` + `LinkButton variant="primary"/"secondary"` | +| 완료 기준 | `home-page.tsx`에 `ui-button` 문자열이 없다. `app-shell-wide-light` 골든 차이가 0이거나, 바뀌면 의도한 것이다 | +| RED 시험 | 별도 RED 없음(리뷰 항목). 바꾼 뒤 FE-GATE-008 visual로 확인한다 | + +### UX-07 ko·en 문구 뜻이 다르고, 오류 요약 항목을 JSX 글자로 잇는다 + +| 칸 | 내용 | +| --- | --- | +| 성격 · 관점 | 확인된 결함 · 23, 9 | +| 심각도·우선순위 · 통제 · 증거 | Low · P3 · M3(키 일치만 `check:i18n`) · E1 | +| 근거 | `form.conflict`: ko는 "…최신 상태를 확인해 주세요."로 행동을 말하고 en은 그 문장이 없다(`catalog.ts:153-154` 대 `:359-360`).
`route.NOT_FOUND.title`: en "Page not found"(문서 제목)와 h1 `page.notFound.title` "Page not found."가 다르다(`:256` 대 `:322`). ko는 같다.
`ErrorSummary`가 `{fieldLabels[name]}: {message}`로 번역 문장 사이에 JSX 글자 ": "를 넣는다(`form-components.tsx:75`) | +| 약속 | fe-ux 체크리스트 "h1이 catalog 제목과 같다", "버튼·오류는 어떻게 고치는지", design-system-platform 9절 금지 "번역 문장 중간에 JSX 문자열을 연결" | +| 최소 개선 방향 | en `form.conflict`에 "Check the latest version."을 더한다. 두 not-found 제목을 맞춘다. `form.errorSummary.item: "{label}: {message}"` 키를 둔다 | +| 완료 기준 | 위 세 곳이 고쳐진다 | +| RED 시험 | locale마다 `route.NOT_FOUND.title === page.notFound.title`인지 보는 unit 시험. en에서 지금 실패한다 | + +### DS-01 스타일 파일이 간격·층·그림자·반경 토큰을 건너뛰고 날 값을 쓴다. 필수 semantic 토큰 7개는 아무 스타일도 읽지 않는다 + +| 칸 | 내용 | +| --- | --- | +| 성격 · 관점 | 확인된 결함 · 3, 22, 23, 21, 25 | +| 심각도·우선순위 · 통제 · 증거 | **Medium · P2** · M1(규칙은 있고 검사는 없다: fe-design-system 함정 1) · E1 | +| 근거 | `src/presentation/styles/theme/*.css`의 padding·margin·gap 날 값 선언이 73개다. 그중 60개는 같은 값의 `--space-*` 토큰이 있다(파일 읽기 스크립트로 셈). `shell.css`, `pages.css`, `templates.css`는 `var(--space-*)`를 한 번도 쓰지 않는다. 예: `templates.css:29` `gap: 1.25rem`, `:87` `padding: 1rem`, `:14-15` `font-size: 0.8rem; font-weight: 800`, `:128` `font-size: 1.1rem`.
토큰과 같은 값을 손으로 쓴 곳: `primitives.css:17`·`:161` `min-height: 2.75rem`(= `--size-control-md`), `primitives.css:375`·`shell.css:140`·`pages.css:155` `999px`(= `--radius-full`).
층: `shell.css:47` `z-index: 30`(= `--layer-sticky`), `responsive.css:19` `50`(= `--layer-navigation`), `templates.css:143` `10`, `shell.css:16` `100`.
그림자: 카드·패널이 `--elevation-panel` 대신 날 그림자를 쓴다(`primitives.css:286`, `pages.css:159`, `.ui-panel`의 Tailwind `shadow-sm`, `primitives.css:9`). dialog는 `--radius-modal` 대신 `--radius-surface`를 쓴다(`primitives.css:409`). 가림막 비율은 `--opacity-scrim: 0.55`가 있는데 `--dialog-backdrop-weight: 55%`로 다시 적었다(`component.css:167`).
`token-contract.ts:17-44`가 필수로 적은 semantic 토큰 가운데 `--layer-navigation`, `--layer-modal`, `--opacity-scrim`, `--opacity-skeleton`, `--elevation-panel`, `--color-disabled-content`, `--color-action-pressed`를 읽는 스타일이 0개다 | +| 발생 조건 | 파생 서비스가 밀도·층·그림자를 토큰으로 조절할 때(PRODUCT의 업무 도구·일반 서비스·랜딩) | +| 영향 | `--space-*`, `--layer-*`, `--opacity-scrim`, `--elevation-panel`, `--radius-modal`을 바꿔도 셸·페이지 템플릿·카드가 그대로다. UI-03의 이유 문장(`design-system-rules.ts:78-80` "규칙을 바꿔도 아무것도 바뀌지 않는다")과 같은 실패가 semantic 층에서 난다. 템플릿 소유 CSS라 모든 파생 서비스에 복제된다 | +| 약속 | `src/presentation/AGENTS.md` "토큰 밖 색·간격을 쓰지 않는다", `docs/styling/design-tokens.md` "component는 … 간격, 글자, … 모서리 반경 토큰을 정적 class로 쓴다"와 「이름 있는 semantic 토큰을 먼저 쓴다」, `PRODUCT.md` 원칙 3 | +| 최소 개선 방향 | (1) 날 간격·글자 크기·반경·z-index·그림자를 토큰이나 Tailwind scale로 바꾼다. 맞는 단계가 없는 값(0.45, 0.65, 0.85rem 등)은 가까운 단계로 반올림하거나 scale에 단계를 더한다. (2) 층은 `--layer-*`, 패널 그림자는 `--elevation-panel`, dialog는 `--radius-modal`, 가림막은 `--opacity-scrim`을 읽는다. (3) `check:design-system`에 두 규칙을 더한다. styles 아래 길이·z-index·box-shadow 날 값 거절(허용: `0`, `1px` 테두리, `%`), 그리고 `REQUIRED_SEMANTIC_TOKENS`에도 `unreadTokenFailures` | +| 완료 기준 | 위 날 값 0건(허용 목록 제외). 필수 semantic 토큰마다 읽는 스타일이 있다. 골든 차이는 반올림으로 생긴 것만이고, 커밋 본문에 이유가 있다 | +| RED 시험 | `tests/unit/design-system-rules.test.ts`에 `unreadTokenFailures(REQUIRED_SEMANTIC_TOKENS, styles)`를 더한다. 지금 7건으로 실패한다. 날 길이 규칙은 거절 fixture와 통과 fixture를 함께 둔다. 죽은 토큰 확인은 실험 X-03 | + +### DS-02 갤러리를 story로 옮기면서 두 갤러리의 전체 화면 axe 검사를 잃었다 + +| 칸 | 내용 | +| --- | --- | +| 성격 · 관점 | 확인된 결함(결함 패턴 T10) · 10, 21 | +| 심각도·우선순위 · 통제 · 증거 | **Medium · P2** · M1 · E1 | +| 근거 | `bbde570`에서는 `/examples/ui`·`/examples/states`가 등록 라우트였다(`platform-examples-contract.ts:15-40`). 그래서 `tests/e2e/accessibility.spec.ts`의 라우트 순회가 두 화면 전체에 axe를 돌렸다.
지금은 다음뿐이다. `tests/storybook/galleries.spec.ts:58-72`는 열린 대화 상자(`.include(".ui-dialog")`)만 본다. `workshop.spec.ts:8-28`은 overlay story 하나만 본다. ScreenStates story와 DesignSystem story 전체, `Primitives`·`LongPseudoLikeContent` story는 어느 시험도 axe를 돌리지 않는다.
옮긴 커밋 `c7e80f2f` 본문의 옮긴 목록에도 전체 화면 axe가 없다.
`.storybook/preview.tsx:118-119` `a11y.test: "error"`는 이것을 돌릴 runner(addon-vitest, test-runner)가 `package.json`에 없어 효과가 없다. 시험은 `a11y.manual:!true`로 addon도 끈다 | +| 발생 조건 | 상태 화면(로딩·빈·오류·인증·권한·없음)이나 갤러리 primitive에 critical·serious axe 위반이 생길 때 | +| 영향 | merge 게이트가 그 위반을 통과시킨다. 템플릿은 기능이 0개라 accessibility.spec이 보는 라우트는 셋(APP_HOME, EXAMPLES_PLATFORM, NOT_FOUND)뿐이다. 그래서 `EmptySurface`·`TerminalErrorSurface`·`AuthRequiredSurface`·`ForbiddenSurface`는 템플릿 상태에서 axe를 전혀 받지 않는다 | +| 약속 | ADR VD-08 결정 3 "interaction과 story-level axe는 Playwright가 정적 Storybook을 대상으로 실행한다", design-system-platform 10.1 "a11y 결과를 CI에서 error로 처리" | +| 최소 개선 방향 | `tests/storybook`에 axe 시험을 더한다. 모든 story(또는 최소 갤러리 둘과 DS story 셋)를 light·dark에서 열고 WCAG 태그 critical·serious 0을 단언한다. 효과 없는 `a11y.test`는 지우거나 실제 runner와 잇는다 | +| 완료 기준 | 위 story 전부에 axe가 돈다. 위반을 넣는 변이가 `test:storybook`에서 실패한다 | +| RED 시험 | 실험 X-01의 probe가 지금 위반을 보고하는지 본다. 고친 뒤에는 `TerminalErrorSurface`의 `aria-labelledby`를 없는 id로 바꾸는 변이가 새 시험에서 실패해야 한다 | +| 넘김 | 위반 내용 판정은 fe-a11y | + +### DS-03 공개 배럴 컴포넌트 상당수에 story가 없고, 결과 불명 화면은 갤러리·골든에 없다 + +| 칸 | 내용 | +| --- | --- | +| 성격 · 관점 | 확인된 결함 · 10, 21, 20 | +| 심각도·우선순위 · 통제 · 증거 | Low · P2 · M0 · E1 | +| 근거 | `src/presentation/design-system/index.ts`의 값 export 71개 가운데 story 파일에 나오는 것은 26개다.
story가 없는 것:
- primitive: `SearchField`, `ConfirmationDialog`, `Drawer`, `Popover`, `Breadcrumbs`, `Pagination`, `LinkButton`, `Separator`, `IconButton`(단독)
- pattern: `DataTable`, `DisclosureGroup`, `PaginationBar`, `SearchFilterToolbar`, `AccessSurface`
- 템플릿 다섯: `StandardPage`, `CollectionPage`, `DetailPage`, `FormPage`, `StatusPage`
- 폼: `ErrorSummary`, `FormFailureStatus`, `DirtyNavigationDialog`, `FormActions`
- 아이콘 9개
`AsyncSurface`는 refreshing만 있다(`galleries.stories.tsx:363-389`). 결과 불명(확인·같은 요청 다시 보내기), 충돌, stale, 저장 중이 없다.
있는 story도 variant 하나씩이다(`design-system.stories.tsx:31-68`). theme·locale toolbar가 없다(`preview.tsx`에 `globalTypes` 없음, `platform.visual.spec.ts:96-97` 주석) | +| 영향 | fe-ux 함정 8의 핵심 화면(결과 불명), 페이지 템플릿, 폼 오류 요약의 배치 회귀를 골든과 story가 잡지 못한다. 파생 서비스가 쓸 컴포넌트의 상태 행렬을 볼 곳이 없다 | +| 약속 | fe-design-system 체크리스트 "필수 story가 있다: default, 모든 variant, disabled·readonly, pending, 오류, 긴 문구, 빈 값, light·dark, compact, 키보드", 함정 11, design-system-platform 10.2·13절("story 없이 runtime gallery 하나로 모든 variant를 대표" 금지) | +| 최소 개선 방향 | 1단계: ScreenStates 갤러리에 결과 불명(재전송 가능)·충돌·stale·StatusPage·FormFailureStatus·ErrorSummary를 더하고 `state-surfaces-light` 골든을 갱신한다(이유는 본문에). 2단계: overlay·form primitive부터 CSF story(variant·disabled·pending·error·긴 문구)를 쓴다. 3단계: theme·locale `globalTypes` decorator | +| 완료 기준 | 화면 컴포넌트 export마다 story가 하나 이상 있다(시험이 대조). 결과 불명 surface가 골든에 든다 | +| RED 시험 | unit 시험: `index.ts`의 PascalCase 값 export가 어느 `*.stories.tsx`에 나오는지 대조한다(허용 목록: `Portal`, `FocusRing`, `VisuallyHidden`, hook). 지금 30개 이상으로 실패한다 | + +### DS-04 시각 골든의 색 허용치(기본 threshold 0.2)가 토큰 색 변경을 통과시킨다. 알려진 제한으로만 적혀 있다 + +| 칸 | 내용 | +| --- | --- | +| 성격 · 관점 | 미검증(작성자 실험 주장, E0 → 실험 X-02) · 21, 10 | +| 심각도·우선순위 · 통제 · 증거 | Low · P2 · M3(픽셀 수만) · E0 | +| 근거 | `playwright.visual.config.ts:41-51`는 `maxDiffPixels: 50`만 정하고 `threshold`를 두지 않는다(Playwright 기본값 0.2).
`CHANGELOG.md:148` 알려진 제한에 적혀 있다. 커밋 `c7e80f2f` 본문에 따르면 어두운 `--color-danger` red-500→600과 밝은 `--color-danger-surface` 색상각 25→145가 옛 골든과 새 골든을 모두 통과했다 | +| 영향 | 위험 표면이 초록빛으로 바뀌어도 골든이 통과한다 | +| 약속 | VD-08 결정 8 "실제 … theme 또는 상태 변화가 숨겨지도록 … 하지 않는다", fe-design-system 함정 10, 소유자 프로그램의 "기록만 하지 않고 고친다" | +| 최소 개선 방향 | `toHaveScreenshot`에 더 작은 `threshold`(0.05 정도)를 둔다. 기준을 **올리는** 쪽이라 꼭 지킬 것 4에 걸리지 않는다. 글꼴이 고정된 깨끗한 빌드는 0 px 차이라는 기존 주장(`playwright.visual.config.ts:45-47`)을 반복 실행으로 확인한다 | +| 완료 기준 | 위 두 변이가 `test:visual`에서 실패하고, 변이 없이는 3회 모두 통과한다 | +| RED 시험 | X-02 | + +### DS-05 1106/08-03이 더한 component 토큰 셋이 `token-contract.ts`에 없어 UI-03 검사 밖이다 + +| 칸 | 내용 | +| --- | --- | +| 성격 · 관점 | 확인된 결함 · 21, 23 | +| 심각도·우선순위 · 통제 · 증거 | Low · P3 · M3(목록에 있는 것만) · E1 | +| 근거 | `component.css:167-177`의 `--dialog-backdrop-weight`, `--dialog-backdrop`, `--dialog-backdrop-on-surface`가 `REQUIRED_COMPONENT_TOKENS`(`token-contract.ts:46-56`)에 없다.
검사는 그 목록만 본다(`check-design-system.ts:102-105`). 그런데 문서는 "UI-03: 모든 component 토큰은 어떤 스타일이든 하나에서 읽힌다"라고 적는다(`design-tokens.md:24`) | +| 영향 | 목록에 없는 component 토큰은 읽히지 않아도 게이트가 모른다. 문서 문장보다 검사가 좁다 | +| 약속 | fe-design-system 체크리스트 "새 component 토큰은 `token-contract.ts`에 이름이 있고 어떤 스타일이 읽는다 — UI-03" | +| 최소 개선 방향 | 세 토큰을 contract에 더한다. `--dialog-backdrop-weight`는 DS-01과 함께 semantic `--opacity-scrim`으로 대신한다(`calc(var(--opacity-scrim) * 100%)`). 검사가 `component.css`에 정의된 이름 전부를 contract와 대조하게 한다 | +| 완료 기준 | `component.css`의 정의와 contract 목록이 같고, 그 대조를 시험이 한다 | +| RED 시험 | unit 시험: `component.css`의 `--x:` 정의 ⊆ `REQUIRED_COMPONENT_TOKENS`. 지금 3건으로 실패한다 | + +### DS-06 `semantic.css`가 팔레트를 거치지 않은 날 `oklch()` 36개를 정의한다 + +| 칸 | 내용 | +| --- | --- | +| 성격 · 관점 | 확인된 결함(문서와 코드가 다름) · 3, 23, 9 | +| 심각도·우선순위 · 통제 · 증거 | Low · P3 · M0 · E1 | +| 근거 | 밝은 테마 13개(`semantic.css:82`, `:85-96`: focus, info·success·warning·danger의 content·surface·border), 어두운 테마 23개(`:124-152`). `PRODUCT.md:31` "토큰은 primitive → semantic → component 세 단계로 파생된다", `design-tokens.md:3-7` "`primitive.css`에는 … 팔레트 … `semantic.css`는 그것을 역할에 연결" | +| 영향 | 팔레트만 바꿔 리브랜드하면 status 색, focus, 다크 테마 대부분이 그대로다 | +| 약속 | 위 두 문장, fe-design-system 체크리스트 "새 값은 primitive → semantic → component 순서로 파생" | +| 최소 개선 방향 | 권하는 안: status 색조(green·amber·info)와 다크 단계를 `primitive.css` 팔레트로 옮기고 semantic이 참조한다. UI-01 계산은 var 사슬을 따라가므로(`oklch-contrast.ts:53`) 막히지 않는다. 다른 안: 문서를 "semantic은 역할 전용 값을 가질 수 있다(목록)"로 고친다 | +| 완료 기준 | semantic 값이 `var()`·`color-mix()`·키워드뿐이거나, 문서가 예외 목록을 적는다 | +| RED 시험 | unit 시험: `semantic.css` 선언값에 `oklch(` 0건. 지금 36건으로 실패한다 | + +### DS-07 primitive의 `className`·`style`이 범위 없이 열려 있다 + +| 칸 | 내용 | +| --- | --- | +| 성격 · 관점 | 구조적 위험 · 22, 21 | +| 심각도·우선순위 · 통제 · 증거 | Low · P3 · M0 · E1 | +| 근거 | `Button`은 `ButtonHTMLAttributes` 전체(`style` 포함)와 `className`을 그대로 넘긴다(`button.tsx:8-14`, `:42-48`). `TextField`(`text-field.tsx:5-14`, `:40`), `LinkButton`(`link-button.tsx:15-23`), `IconButton`, `Card`(`card.tsx:9`), `Dialog`(`dialog.tsx:21`)도 같다.
`check:design-system`은 TS에서 `#hex`·`oklch(`·`rgb(`만 찾는다(fe-design-system 함정 1). 그래서 `style={{ color: "red", padding: 13 }}`은 게이트를 지난다. 범위를 적은 문서가 없다(`git grep className -- docs/styling docs/manual` 0건) | +| 영향 | 기능 화면이 primitive 위에 날 색·간격을 얹어도 막는 것이 없다 | +| 약속 | fe-design-system 함정 7 "범위 없는 `className`", design-system-platform 11절 4단계 "`className` escape hatch의 범위를 정한다" | +| 최소 개선 방향 | 공개 props에서 `style`을 뺀다(`Omit<…, "style">`). `className`은 "배치용(그리드 위치·여백)만"이라고 JSDoc과 `design-tokens.md`에 적는다 | +| 완료 기준 | `