Files
clean-architecture-frontend…/docs/manual/reference/errors.md
T
DongHyeonka aa4bddac36 fix(a11y): 수동 접근성 기록이 릴리스 태그로 서명되고 WCAG 2.2 칸을 갖는다
수동 접근성 기록 검사에 구멍이 둘 있다.
- FE-GATE-028(`review:a11y-manual`)은 기록끼리 Release ID가 같은지만 본다
  (05-01). 후보를 받는 입력이 없어, 첫 release에 세 기록을 서명한 뒤 화면을
  바꾸고 기록을 그대로 둔 채 다음 release를 돌아도 통과한다. checklist의
  "release 후보마다 한 번"이 지켜지지 않는다(결함 패턴 G7).
- 제품은 WCAG 2.2 AA를 약속하는데 기록 양식은 M1~M7과 스크린 리더뿐이다
  (05-05의 남은 것). axe에 규칙이 없는 2.4.11 포커스 가림과 일부만 보는 2.5.8
  목표 크기를 볼 칸이 없다.

고른 방법:
- 결정(2026-11-13, r9-fe·w2-fe-2: 후보 ID는 릴리스 태그)대로
  `scripts/verify-a11y-manual.ts`가 env `RELEASE_TAG`를 읽고, 각 기록의
  `Release ID`가 그 태그와 같지 않으면 실패한다. 태그가 비면 비교할 것이 없으니
  모두 실패한다(fail-closed). release job은 이미 `RELEASE_TAG`를 넘기고
  FE-GATE-028이 그것을 요구한다(main `000b5a35`). 규칙은
  `releaseTagFailures`(`scripts/lib/manual-a11y-evidence.ts`)에 둔다.
- 결정 R9-D9(2026-11-12, 총괄)대로 기록 양식에 `M8 Focus not obscured`
  (2.4.11)와 `M9 Target size`(2.5.8)를 더한다: 검사기의 필드 목록, checklist,
  템플릿 기록 셋, `create:feature`가 만드는 기록. checklist의 `Release ID` 예는
  "release tag"로 바꿨다.
- 버린 대안: workflow의 `RELEASE_ID`와 대조(run마다 달라 사람이 미리 적을 수
  없다), 칸 없이 태그만 더하기(2.2 AA 일부를 아무도 보지 않는다).

위험·한계: 다운스트림의 기존 route 기록에는 M8·M9가 없어 다음 동기화 뒤
FE-GATE-009 형식 검사가 그 필드 이름을 대며 실패한다. 기록마다
`M8 Focus not obscured: pending`, `M9 Target size: pending` 두 줄을 더하면 된다.
서명한 기록의 `Release ID`는 다음 release부터 태그(예 `v1.4.0`)로 적는다.

검증: `tests/unit/manual-a11y-evidence.test.ts`(M8·M9가 빠진 기록 거절, 태그
같음·다름·빔, `review:a11y-manual`을 실제로 띄워 태그로 통과·다음 태그와 빈
태그로 실패)가 고치기 전 코드에서 실패하고 고친 뒤 통과한다(desktop, PR 본문).

Refs: 1112/05-01, 1112/05-05
2026-11-13 18:45:16 +09:00

22 KiB

실패 메시지와 고칠 파일

기능을 만들 때 흔히 보는 실패 메시지다. 메시지는 코드의 문자열을 그대로 옮겼다. <...>는 실제 값이 들어가는 자리다.

찾는 법: 메시지 앞부분으로 이 문서를 검색한다. 없으면 git grep '<메시지 앞부분>' -- src scripts로 코드를 찾는다. 코드가 정본이다.

메시지가 어느 단계에서 나오는지:

create:feature        → 명령이 파일을 쓰기 전에 거부
generate:feature-index → 모든 빌드·검사 명령이 먼저 돌린다
조립·모듈 로드         → 테스트, 빌드, 앱 부팅 어디서든
check:registries      → FE-GATE-010
lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010
문서·접근성            → FE-GATE-017, FE-GATE-009, FE-GATE-028
릴리스 승인·공급망      → FE-GATE-027, FE-GATE-012
제거 드릴              → FE-GATE-020

<base>는 기능 ID에서 끝의 -feature를 뗀 것이다.


생성 명령 (create:feature)

모두 create:feature: 뒤에 나온다. 종료 코드는 1이다(인자 오류는 2).

메시지 원인 고칠 곳
feature id "<id>" must be kebab-case (lower-case words joined by single hyphens), at most 40 characters ID 형식 명령 인자
context id "<context>" must be kebab-case (lower-case words joined by single hyphens), at most 64 characters --context 형식 명령 인자
feature id <id> is already a feature or context 같은 ID가 있다 다른 ID
feature id <id> would prefix its ids with "<base>", which <other> already uses 접두어가 기존 기능과 같다 다른 ID
context <context> already exists; pass --context <context> to add the feature to it 새로 만들 context가 이미 있다 --context <context>를 준다
context id <context> is a feature id context ID가 기능 ID와 같다 다른 --context
src/contexts has a <context> directory without a context declaration 선언 없는 context 폴더 src/contexts/<context>/context-module.ts를 만들거나 폴더를 지운다
another context already owns the route root <root>/* 같은 라우트 루트를 다른 context가 가진다 다른 ID, 또는 그 context에 --context로 넣는다
a new context needs exactly one deployable app (declared: <apps>); pass --context <an existing context> 앱이 여럿이라 새 context의 소속을 정할 수 없다 --context
route <ROUTE_ID> (<path>, <chunkId>) collides with installed route <ROUTE_ID> (<path>, <chunkId>) route ID·경로·chunk가 겹친다 다른 ID
message keys already exist: <keys> 문구 키가 겹친다 다른 ID
generated topic <topic> is already installed; run the command again 무작위 topic이 우연히 겹쳤다 명령을 다시 돌린다
contract package <packageId>@<version> is not a pinned identity: <reason> 패키지 신원 형식. <reason> 예: <id>: package version must be exact SemVer, <id>: package digest, <id>: package sourceRevision, <id>: packageId --package, --digest, --revision
--package, --digest and --revision go together. ... 셋 중 일부만 줬다 셋을 함께 준다
--package must be @scope/name@<exact version>. ... 버전 없는 패키지 이름 @scope/name@1.2.3 꼴
--keyed needs --with-create. ... --keyed만 줬다 --with-create --keyed
refusing to overwrite: <paths> 쓸 파일이나 기능 폴더가 이미 있다 그 경로를 확인하고 지우거나 다른 ID
the feature index generator rejected the feature, nothing was kept: 생성기가 거부했다. 만든 파일은 모두 지웠다 뒤따르는 생성기 메시지(아래 절)

생성기 (generate:feature-index)

메시지 원인 고칠 곳
Feature <id> belongs to undeclared context <context> context 선언이 없거나 FEATURE_CONTEXT_ID 오타 src/contexts/<context>/context-module.ts, 또는 src/features/<id>/feature-module.ts
Context <context> belongs to undeclared app <app> CONTEXT_APP_ID 오타 src/contexts/<context>/context-module.ts
<file> must export a literal <NAME> 헤더를 상수 참조나 식으로 썼다. 생성기는 글자로 읽는다 그 파일. export const <NAME> = "<값>"; 꼴
<file> must export a positive integer <NAME> 예산 값이 정수 리터럴이 아니다 그 파일
src/features/<dir> has no feature-module.ts; add one, or keep code that is no feature outside src/features 기능 폴더에 선언 파일이 없다 feature-module.ts를 만든다. 기능이 아닌 코드(시험용 소비자 등)면 src/features/ 밖으로 옮긴다
Duplicate generated feature ids: <id> 두 폴더가 같은 FEATURE_MODULE_ID 한쪽 feature-module.ts
Duplicate context id: <id> 두 폴더가 같은 CONTEXT_MODULE_ID 한쪽 context-module.ts
Context <context> feature cardinality <n> exceeds budget <max> context의 기능 수가 예산을 넘었다 CONTEXT_MAX_FEATURES, 또는 새 context
App <app> context cardinality <n> exceeds budget <max> 앱의 context 수가 예산을 넘었다 src/apps/<app>/app-module.ts의 APP_MAX_CONTEXTS

조립·모듈 로드

테스트, 빌드, 앱 부팅 어디서든 나온다. 한 기능의 실수가 거의 모든 게이트를 같이 실패시킨다. 첫 메시지를 본다.

인증 프로필

메시지 원인 고칠 곳
<featureId>/<operationId>: unknown authProfileId <id> (계약 조립 오류의 reason) 없는 인증 프로필 contracts/<base>-contract-contribution.ts의 frontend.authProfileId. 제품 프로필이면 src/contracts/product-contracts.ts
<featureId>/<operationId>: <METHOD> with cookie profile <id> must require x-csrf-token or x-xsrf-token (계약 조립 오류의 reason) 쿠키 인증 프로필로 쓰기 요청을 보내는데 프로필이 CSRF 헤더를 요구하지 않는다 src/contracts/product-contracts.ts의 그 프로필 requiredCredentialHeaders. 짝 백엔드는 x-xsrf-token
Product REST auth profile <id> reuses a template profile id. 제품 프로필 ID가 템플릿 것과 같다 src/contracts/product-contracts.ts

계약·스키마·mapper

메시지 원인 고칠 곳
부팅 화면 CONTRACT_SET_PACKAGE_MISSING / CONTRACT_SET_PACKAGE_UNEXPECTED(corepack pnpm dev, dev server를 쓰는 브라우저 테스트) dev manifest public/release-manifest.json의 계약 패키지가 설치된 기능과 다르다. 기능을 손으로 더하거나 지웠다 node scripts/write-dev-release-manifest.ts로 다시 쓰고 커밋한다. tests/unit/dev-release-manifest.test.ts가 같은 어긋남을 잡는다
Invalid or duplicate schema definition: <schemaId> 스키마 ID 중복 또는 메타 형식 contracts/<base>-schema-metadata.ts. 접두어를 붙인다
duplicate operation: <operationId> (계약 조립 오류의 reason) operation ID 중복 contracts/<base>-contract-contribution.ts. 접두어를 붙인다
FE-REG-API.<operationId>.requestSchema references unknown FE-REG-SCHEMA.schemaId=<id> descriptor의 입력 스키마 ID가 스키마 메타데이터에 없다 (responseSchema, problemSchema도 같은 꼴. 실패 본문 행은 boundary: "api-problem") contracts/<base>-schema-metadata.ts
<schemaId>: row <boundary>, used as <boundary> (tests/unit/schema-metadata-policy.test.ts) 스키마 메타 행의 boundary가 그 스키마가 쓰인 자리와 다르다. no FE-REG-SCHEMA row는 쓰이는데 행이 없다 contracts/<base>-schema-metadata.ts
<operationId> <schemaId>: row states no direction, used as <direction> 또는 row states no unknownFieldPolicy, validator <policy> (tests/unit/schema-metadata-policy.test.ts) descriptor가 쓰는 스키마의 행이 direction·unknownFieldPolicy를 적지 않았다(1106/07-02) contracts/<base>-schema-metadata.ts에 두 칸을 적는다. 값은 쓰인 자리와 검증기가 정한다. 객체가 아닌 본문의 검증기(z.undefined() 등)는 direction만 요구한다
Unregistered route codec: <codecId> URL 함수가 기능 codec을 buildRouteUrl에 넘기지 않았다 presentation/<base>-routes.ts
contract package <packageId> is declared, but no loaded contribution pins it 계약 contractPackages에 적은 패키지를 계약 기여가 쓰지 않는다 contracts/<base>-contract-contribution.ts의 source
<id> contributes contract package <packageId>, which no installed feature declares in contracts.contractPackages 계약 기여의 신원과 계약 선언의 신원이 다르다 둘 다 <BASE>_CONTRACT_PACKAGE 하나를 쓰게 한다
contract package <packageId> is declared with conflicting identities 두 기능이 같은 패키지를 다른 버전·digest로 선언했다 두 기능의 <BASE>_CONTRACT_PACKAGE를 맞춘다

계약 조립 실패의 메시지는 Installed contract contribution is not composable: <reason>이다. reason은 오류 객체(ContractContributionError)의 reason 속성에도 있다.

reason 원인 고칠 곳
<id>: TEMPLATE_FIXTURE REFERENCE_FEATURE_V1 belongs to <fixture owner> only; pin an EXTERNAL_PACKAGE 템플릿 fixture 출처(예전 참조 샘플용)를 제품 기능이 썼다 contracts/<base>-contract-contribution.ts의 source를 EXTERNAL_PACKAGE로
duplicate operation: <operationId> 두 기여가 같은 operation ID 접두어를 붙인다
duplicate contributionId: <id> 두 기여가 같은 contributionId contracts/<base>-contract-contribution.ts
<id>/<operationId>: unknown authProfileId <profile> V3 frontend.authProfileId가 없는 프로필 V3 frontend.authProfileId
<id>/<operationId>: retry budget contradicts NEVER retry semantics NEVER인데 retryBudget가 0이 아니다 V3 frontend.retryBudget
<id>/<operationId>: KEYED commands require a recovery descriptor KEYED인데 commandRecovery가 없다 V3 commandRecovery
<id>/<operationId>: <GET·HEAD> is a read; its retrySemantics is SAFE or IDEMPOTENT, not <값> 읽기에 KEYED나 NEVER를 적었다 V3 retrySemantics. 재시도를 막으려면 frontend.retryBudget: 0
<id>/<operationId>: command operations require a command effect descriptor 쓰기에 commandEffect가 없다 V3 commandEffect
<id>/<operationId>: refusedBeforeWrite cannot declare <code>; contract 6.1 reads this platform code as possibly raised after the write commandEffect.refusedBeforeWrite에 계약 문서 6.1절이 "쓰기 뒤 가능"으로 둔 플랫폼 code(BAD_PARAMETER, DB_* 등)를 적었다 그 code를 목록에서 지운다. 그 실패는 결과 불명으로 남는다(02 결정표 4절)
<id>/<operationId>: read operations carry no command descriptors GET에 commandEffect·commandRecovery를 적었다 둘 다 null
<id>/<operationId>: responseEnvelope NONE, but <other> in the same contribution reads ENVELOPE_V1; ... 한 계약 기여 안에서 operation 하나만 응답 모양이 다르다. 손으로 더한 operation에 "NONE"을 적었거나, TypeScript 밖에서 만든 descriptor가 줄을 뺐다 그 operation에 responseEnvelope: "ENVELOPE_V1" as const를 적는다. 정말 다른 백엔드면 기여를 나눈다
check:types: Property 'responseEnvelope' is missing in type ... (descriptor의 satisfies InstalledHttpContract<...>) descriptor에 응답 모양 줄이 없다. 1103/16-01부터 필수 칸이다 짝 백엔드면 responseEnvelope: "ENVELOPE_V1" as const, 감싸지 않는 백엔드면 "NONE" as const
<id>: package version must be exact SemVer 버전 범위(^1.2.0)나 형식 오류 <BASE>_CONTRACT_PACKAGE.version

라우트·context

메시지 원인 고칠 곳
Duplicate route registry key: <ROUTE_ID> route ID 중복 계약 routes. 접두어를 붙인다
Duplicate route runtime contract key: <ROUTE_ID> routeRuntimeContracts 중복 계약 routeRuntimeContracts
Route <ROUTE_ID> (<path>) of feature <id> is not under the route root of its context <context> (<root>): the router would answer NOT_FOUND. 라우트가 context 루트 밖 계약 routes.*.path, 또는 CONTEXT_ROUTE_PATH
Route <ROUTE_ID> (<path>) of feature <id> is not under the route root of its context <context> (<root>): context <other> (<root>) takes that URL. 다른 context의 루트 아래 같은 곳
Route handle <ROUTE_ID> loaded by context <context> is not a contract route of its features (<ids>). context-routes.ts의 handle이 계약에 없는 route ID src/features/<id>/context-routes.ts

문구·서버 상태

메시지 원인 고칠 곳
Duplicate <locale> message key: <key> 문구 키 중복 contracts/<base>-message-catalog.ts. 접두어를 붙인다
Duplicate invalidation topic: <topic> topic 중복. 복사한 topic 계약 invalidation. topic을 새로 만든다
Duplicate invalidation namespace: <key> namespace 중복 defineQueryNamespaceIdentity 이름
Query invalidation topic is invalid. topic 형식이 qinv. + 26자가 아니다 defineQueryInvalidationTopic 값
Orphan invalidation topic: <topic> edge가 없는 topic 계약 invalidation.edges
Unregistered server-state profile: <profileId> 없는 profile 쿼리 바인딩의 profileId
commandMutationIdentity: <operationId> is a GET; a mutation binds a write operation 뮤테이션 정책에 읽기 descriptor를 넘겼다 정책의 commandMutationIdentity(...) 인자를 쓰기 descriptor로

조립 기여

메시지 원인 고칠 곳
feature <id> needs <capability>, which the host did not provide 템플릿이 만들지 않는 capability src/bootstrap/product-composition.ts의 capabilities, 또는 needs
feature adapter contribution <id> installed an input for <other> 기여의 featureId와 만든 input의 featureId가 다르다 adapters/create-<base>-feature-input.ts
duplicate feature adapter contribution: <id> 두 기여가 같은 기능 ID 복사한 기여 파일
Feature <id> installed an input for <other> 지연 로드한 기능이 다른 기능의 input을 냈다 adapters/create-<base>-feature-input.ts

레지스트리 (check:registries)

모두 Registry governance failed: 다음 줄에 나온다.

메시지 원인 고칠 곳
FE-REG-ROUTE.<ROUTE_ID> duplicates path=<path> from <ROUTE_ID> 경로 중복 (chunkId=도 같은 꼴) 계약 routes
FE-REG-ROUTE.<ROUTE_ID>.loadingSurface value <value> does not match <pattern> 로딩 화면 이름이 케밥 표기가 아니다 계약 routes.*.loadingSurface
FE-REG-ROUTE.<ROUTE_ID>.<field> has unknown value <value> access·errorSurface가 정해진 값이 아니다 계약 routes
FE-REG-ROUTE.<ROUTE_ID>.paramsSchema references unknown FE-REG-SCHEMA.schemaId=<id> 라우트 스키마 ID를 기능이 등록하지 않았다 (searchSchema도 같은 꼴) 계약 스키마 메타
FE-REG-API.<operationId> has no executable consumer for operationId=<operationId> 계약의 operation을 기능 adapters/·application/에서 쓰지 않는다 쓰지 않으면 descriptor를 지운다
missing registry source <path>: <message> 레지스트리 source를 읽다가 오류가 났다. 계약 조립 실패면 <message>가 Installed contract contribution is not composable: <reason>이고 <reason>이 위 reason 표의 값이다. 다른 오류가 reason 속성을 message와 따로 가지면 끝에 (reason: <reason>)이 붙는다. 읽지 못한 레지스트리는 removed 증거를 요구하지 않는다 <reason>이 가리키는 곳
breaking change missing evidence: <changeId> 행을 빼거나 바꿨는데 승인이 없다 update:registry-baseline 또는 config/contracts/registry-change-evidence.json
stale breaking evidence <changeId>: no breaking change in the current diff has this changeId. ... 지금 diff와 맞지 않는 증거 행 그 행을 지운다
registry baseline approval digest mismatch: approved=<digest> actual=<digest> 기준선 파일을 손으로 고쳤다 update:registry-baseline으로 다시 찍는다

경계·lint·문구

메시지 원인 고칠 곳
check:architecture 출력의 규칙 이름 (feature-presentation-does-not-know-outbound-adapters 등) 금지된 import 규칙 뜻은 docs/architecture/layers.md의 "Rules" 표가 정본
Screen words come from the message catalog: use message(key) (0929/08-02). 화면에 문자를 직접 썼다 문구 catalog에 키를 더하고 message(key)
en-US catalog keys do not match ko-KR (I18n contract failed: 다음) 두 locale의 키가 다르다 contracts/<base>-message-catalog.ts
en-US:<key> interpolation parameters do not match {name} 자리가 locale마다 다르다 같은 파일

문서·접근성

메시지 원인 고칠 곳
docs/accessibility/route-reviews/ has no record for route IDs: <ids> (verify:documentation) 라우트의 a11y 기록 파일이 없다 기존 pending 기록을 복사해 제목과 Route ID를 바꾼다
Manual accessibility record format is invalid: 다음 docs/accessibility/route-reviews/<ROUTE_ID>.md: missing record (FE-GATE-009) 같은 원인 같은 곳
a11y.json not written: 다음 a11y: <ROUTE_ID> reads one resource (<operationId>) but has no failure-state record in artifacts/tests/a11y-data-state (test:a11y, FE-GATE-009) 라우트의 paramsSchema가 한 자원을 읽는 GET의 입력인데, 접근성 spec이 그 라우트를 실패 화면으로만 봤다는 기록이 없다(1106/11-01). spec이 기록 호출을 놓쳤거나, 그 라우트의 페이지가 그 GET을 부르지 않아 spec이 실패 화면을 보지 않았다. 앞의 경우 그대로면 a11y.json이 그 라우트를 통과로 센다 페이지가 그 GET을 부르면 tests/e2e/accessibility.spec.ts의 기록 호출(recordA11yDataState)을 본다. 이때 기능 파일은 고치지 않는다. 페이지가 그 GET을 부르지 않으면(예: /things/:thingId/parts/new 같은 하위 항목 작성 폼이 상세 GET과 같은 ThingParams를 쓴다) 그 라우트에 자기 paramsSchema를 따로 둔다. 기능의 라우트 계약과 contracts/<base>-schema-metadata.ts를 고친다
Manual accessibility evidence is incomplete: 다음 <ROUTE_ID>: <failures> (FE-GATE-028) 서명하지 않은 기록 03 문서
release IDs do not match (FE-GATE-028) 라우트마다 다른 릴리스로 검토했다 같은 릴리스 후보로 다시 검토한다
<ROUTE_ID>: Release ID "<id>" is not the release tag "<tag>" (FE-GATE-028) 그 기록이 이번 릴리스 태그가 아닌 릴리스(보통 앞 릴리스)로 서명됐다 이번 릴리스에서 다시 검토하고 Release ID를 그 태그로 적어 서명한다(03 문서)
no release tag to compare the Release ID with (RELEASE_TAG is empty) (FE-GATE-028) 태그 run이 아닌 곳에서 서명 검사를 돌렸다. release job은 태그 run에서만 RELEASE_TAG를 채운다 릴리스 태그(v*)를 push한 run에서 돌린다. 손으로 돌리면 RELEASE_TAG=<tag>를 준다
<doc> names paths that do not exist: <paths> (verify:documentation) 문서가 없는 경로를 적었다 그 문서

릴리스 승인·공급망

메시지 원인 고칠 곳
release admission refused for <target>: 다음 contractPackages.<packageId>: pins the placeholder identity create:feature writes; pin the published package's version, digest and revision (FE-GATE-027) 자리표시자 계약 신원으로 공개 대상 승인 03 문서 "자리표시자 계약 신원 교체"
high-risk dependency missing review: add:<name>@<version> (generate:supply-chain) production 의존성을 더했는데 검토 기록이 없다 config/security/dependency-change-evidence.json

제거 드릴

메시지 원인 고칠 곳
<id> removal failed: 다음 fixture-id-residue: residue: <files> (test:sample-removal) 기능을 지운 뒤에도 그 기능을 가리키는 파일이 남았다. src는 기능 ID나 폴더 이름을 담은 파일, tests는 이름이 기능 ID를 담거나 기능 폴더(src/features/<id>/, tests/features/<id>/)에서 import하는 파일, 본문에 -가 든 기능 ID나 폴더 이름을 적힌 그대로 한 이름으로 적은 Playwright spec(*.spec.ts)이다 그 파일을 기능 폴더 안으로 옮기거나, 기능을 가리키지 않게 한다. 지운 기능 전용 spec이면 지운다. 목록에 템플릿 파일이 나오면 템플릿 결함이다. 그 파일을 고치지 말고 템플릿에 알린다
No installed feature declares FEATURE_MODULE_ID "<id>" --feature=에 없는 기능 ID 명령 인자
feature scaffold failed: 다음 <check>: <failure> (test:feature-scaffold) 생성한 기능이 게이트 하나를 통과하지 못했다 scripts/create-feature.ts의 템플릿. 제품 팀이 아니라 템플릿을 고칠 일이다