22 Commits
Author SHA1 Message Date
DongHyeonka eb9ec75cee merge: PR #29을 합친 검사 브랜치에 넣는다 2026-11-13 07:16:02 +09:00
DongHyeonka 06ffafa25e docs: 살아 있는 문서의 낡은 문장을 지금 코드와 정본에 맞춘다
2026-11-07~08의 정리(문서 이동, 참조 기능 삭제, CI 재편) 뒤 살아 있는
문서가 지금 코드와 다른 말을 한다.

- 현재 계약 문서 둘과 스타터 문서가 기록(docs/design/)을 정본으로
  가리킨다. 정본을 frontend-application-foundation.md·src/bootstrap/,
  패턴 표·계층 규칙으로 바꾸고 설계서는 배경으로 둔다(1112/02-06).
- 실시간 대응표 둘(짝 백엔드 출구, poll attempt 결과)이 기록에만 있었다.
  optional-adapter-recipes.md로 옮기고 코드 주석·매뉴얼 03·설계서 머리
  블록이 옮긴 곳을 가리킨다(1112/09-02).
- 실행 격리 변수 목록을 설계 기록이 아니라 scripts/lib/run-isolation.ts로
  가리킨다(1112/08-17).
- 계약 소유 절 이름(「판단 규칙」), pin 대조 시험의 게이트(005·007),
  drift 검사 범위(1112/02-07). INVENTORY 머리의 손 숫자와 지킬 수 없는
  꼬리 문장(1112/02-08).
- 검증 안내: 검사기를 바꾸면 FE-GATE-029, 문서면 desktop
  verify:documentation(1112/08-05, 08-04). FE-GATE-012는 merge 단계다
  (08-16). N6이 알리는 파일을 좁혀 적는다(08-10). 한 파일 시험은
  verify.sh exec(08-11). 문서 검사 범위의 손 사본을 정본 한 곳으로(08-07).
- create:feature 참조의 Next: 3과 되돌리기(08-08), 손으로 옮긴 숫자
  (08-19), 라운드 없는 리뷰 ID 17곳에 0925를 붙인다(08-15).
- secret scan 범위 설명(1112/07-03), lab이 기능 라우트를 읽는 문장
  (1103/16-06), README 동기화 기준점·제품 소유 파일·선택 기능 결함 몫
  (0929/14-02, 14-03, 13-10), 커밋을 다시 지은 모든 통합의 해시 대조
  (1106/14-02).

고른 방법: 문장을 코드에 맞춘다. 표는 옮기고 숫자는 정본을 가리킨다.
버린 대안: 기록 문서 본문 고치기(기록은 머리 블록만 고친다).

위험·한계: 문서 검사 범위 목록을 지운 ci-quality-gates.md는 이제
docs/README.md 5절과 gates.md 7절을 읽어야 한다. 매뉴얼 02 7절 업로드
예의 declare module 문제(1112/09-01)는 고치는 방향이 check:architecture
규칙과 부딪쳐 결정 대기로 남긴다.

검증: scripts/verify.sh docs(노트북) 통과. desktop verify:documentation과
FE-GATE-005(문서를 읽는 시험)는 PR 본문에 적는다.

Refs: 1112/02-06, 1112/02-07, 1112/02-08, 1112/07-03, 1112/08-04,
 1112/08-05, 1112/08-07, 1112/08-08, 1112/08-10, 1112/08-11, 1112/08-15,
 1112/08-16, 1112/08-17, 1112/08-19, 1112/09-02, 1103/16-06, 0929/14-02,
 0929/14-03, 0929/13-10, 1106/14-02
2026-11-12 23:36:14 +09:00
DongHyeonka 4ab35c4a05 fix(test): 템플릿 시험이 사본에 만드는 기능 ID를 예약 접두어로 옮긴다
frontend-quality-gates / merge / static checks (pull_request) Successful in 2m50s
frontend-quality-gates / merge / tests (pull_request) Failing after 14m15s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 10m29s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
frontend-quality-gates / main / checker self-tests (pull_request) Skipped
템플릿 시험과 드릴이 저장소 사본에 고정 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
2026-11-12 22:32:09 +09:00
donghyeon.kang 79dc945a67 refactor(layout): 루트 경로 목록을 등록부 하나에서 고르고 schemas/를 옮긴다
루트 항목 하나를 옮기려면 코드 7곳의 루트 경로 목록을 같이 고쳐야
했다(복사 대상, 비밀값 검사 범위, 공급망 시험의 필수 입력, 이력 문서
검사, 규모 입력, vite 입력, TS 전용 규칙). 서로 다른 부분집합이고 한
곳에서 선언하지 않았다. 목록이 갈라져 공급망 생성이 깨진 적도 있다
(removal-fixture.ts 주석). 루트에는 JSON Schema 5개만 담은 `schemas/`가
`config/` 옆에 따로 있었다. `artifacts/`(출력 폴더)에는 사람이 쓴 수동
a11y 기록이, `config/hosting/`(호스트 계약)에는 시험 fixture가 섞였다.

고른 방법(design-docs repo-structure/04-frontend-layout.md 9.2절 3단계,
11절 R1·R2, 소유자 승인 2026-11-07):
- `config/repository-layout.json`이 루트 항목마다 종류·역할·읽는 곳과
  들어가는 목록(`sets`, 항목 안 경로는 `setPaths`)을 적는다.
  `scripts/lib/repository-layout.ts`가 읽고 검증한다. 6곳은 이름 붙은
  집합을 고른다. JSON인 비밀값 검사 정책은 집합의 사본을 두고 시험이
  같은지 본다(정책 파일은 릴리스 후보에 실려 형식을 바꾸지 않았다).
  공급망 시험의 필수 입력 목록은 그 시험으로 대신한다.
- `tests/unit/repository-layout.test.ts`: 등록부에 없는 루트 항목이
  추적되면 실패(R1). 7곳이 등록부 모듈을 쓰고 루트 이름 둘 이상의
  문자열 배열을 갖지 않는지(R2).
- `schemas/artifacts/` → `config/schemas/artifacts/`, recipe 카탈로그
  스키마 → `config/schemas/recipes/`. 정책 입력 순서(ASCII)에 맞춰
  `config/schemas/`가 `config/security/` 앞에 온다.
- 수동 a11y 기록 3개 → `docs/accessibility/route-reviews/`. `artifacts/`는
  `.gitkeep`만 추적한다. 기록은 단위 시험이 읽어서 drill 사본에도
  복사한다(`fixture-copy` 집합의 `docs/accessibility/route-reviews`).
- `config/hosting/response-headers.fixture.json` →
  `tests/fixtures/hosting/response-headers.json`.

버린 것: 비밀값 검사 정책이 집합 이름을 참조하게 바꾸는 방법. 정책
파일은 릴리스 후보와 로컬 증거 평가가 읽는 형식이라 바꾸면 릴리스
증거 계약이 바뀐다. 루트 항목이 지워졌는데 등록부에 남는 경우는
시험하지 않았다. drill 사본은 일부만 복사해 그 방향을 볼 수 없다.
그런 항목은 그 집합을 쓰는 곳(복사, 비밀값 검사)에서 실패한다.

위험: 하네스 작업(fe-c)이 더할 `AGENTS.md`·`.claude/`를 미리 등록했다
(optional). 등록부가 이력 문서(`SPEC.md`)와 `CLAUDE.md` 이름을 적어서
이력 문서 검사에서 등록부 파일은 뺐다. 다운스트림은 자기 루트 항목을
등록부에 더해야 한다(CHANGELOG). CI 계약 기준선을 다시 받았다(a11y
기록 산출물 id·경로).

검증(desktop): 아래 4단계 커밋까지 쌓은 트리에서 test:unit,
check:types, check:ci, lint, verify:documentation을 돌렸다(그 커밋에
적음). 이 커밋 단독으로 test:unit·check:ci·check:types를 돌렸다.

Refs: design-docs repo-structure/04-frontend-layout.md 2.4·9.2·11절, README.md 3.4절
2026-11-08 17:41:07 +09:00
DongHyeonka e3c8db48ae chore(features): 참조 기능과 예제 화면을 지우고 레지스트리를 다시 승인한다
소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.4절)으로
템플릿 샘플을 지운다. 샘플이 맡던 시험 대상은 앞 커밋들이 옮겼다.

참조 기능과 예제 화면, 두 context, 그 시험, e2e 3개, 수동 접근성 기록
7개, 런타임 프로필 키, test:reference-feature(명령, 산출물, 게이트
참조), 커버리지 정책 행을 지웠다. removable-template-features 목록은
비우고 장치는 남겼다: test:sample-removal은 인자가 없으면 목록을
하나씩 지우고, 비면 SKIP을 출력하고 보고서에 건너뛴 사례를 남긴다.
기능 스위치 시험과 홈 시작 링크 스위치 시험은 시험 전용 fixture 기능으로
옮겼다. browser soak은 생성 기능을 넣은 빌드에서 돈다. 문서의 샘플
경로를 고쳤다. 날짜가 붙은 설계·리뷰 기록의 본문은 그대로 두었다.
레지스트리 기준선(update:registry-baseline, OWNER DongHyeonka), CI 계약
기준선과 workflow, 초기 JS 기록(194,354B, 17파일, 첫 기능 6,327B, 기능
539B, context 4B)을 다시 받았다.

위험: 레지스트리 행 삭제는 breaking이다. 샘플을 고쳐 쓰는 다운스트림은
수정/삭제 충돌을 만난다. 성능 lab의 기능 라우트 측정은 템플릿에
공개 기능 라우트가 없어 measured:false다. TEMPLATE_FIXTURE 출처는
플랫폼 코드에 남았다.

검증(desktop): check:types, lint, check:architecture, check:registries,
check:ci, verify:documentation, test:unit, test:component,
test:contract, test:integration, test:recipes, test:coverage(Risk
coverage PASS 378/378, 문턱 68개), test:e2e 183, test:a11y, test:visual,
test:storybook, test:browser-capabilities, test:feature-scaffold PASS(76
checks), test:sample-removal SKIP, build, check:bundle.
2026-11-08 14:07:58 +09:00
DongHyeonka 01cac930e0 docs(manual): 샘플 대신 생성 기능 경로와 시험하는 코드 조각을 예제로 둔다
매뉴얼 예제 칸 14곳(S4 3.3절)과 산문 30여 곳이 참조 기능을
가리킨다. problem details(Envelope가 아닌 백엔드) 응답 매핑의 예는
참조 기능에만 있다.

생성기 출력이 그 모양을 만들면 그 경로로 바꿨다. 없으면 매뉴얼 안
코드 조각으로 썼다: problem details의 분류와 매핑(02 결정표 4절,
소유자 결정 D1), 도메인 모델, 검색값 스키마와 hook, 실패 행동 hook,
403 페이지 시험. 조각마다 manual-code-block 표식에 둘 경로를 적는다.
tests/unit/manual-code-blocks.test.ts가 저장소 사본에 create:feature
invoice-feature --with-create를 만들고 조각을 그 경로에 그대로 넣어
tsc(app, test), eslint, check:architecture, 그 기능 폴더의 vitest를
돈다. 조각의 동작은 tests/fixtures/manual-code-blocks/가 본다.

위험: 403 조각은 본문 없는 403으로 답한다. 공유 시나리오
forbidden-403(JSON 본문)은 jsdom + MSW에서 실행기의 본문 cancel이
끝나지 않아 화면이 로딩에 머물렀다. 실행기는 고치지 않았다. 사본에
이미 invoice-feature가 있는 프로젝트에서는 이 시험이 생성 단계에서
실패한다.

검증(desktop): test:unit 213 files 3096 passed(이 커밋까지),
verify:documentation PASS_SCOPED, lint 통과.
2026-11-08 13:51:55 +09:00
DongHyeonka 116cbf3d06 fix(scaffold): 저장 중에 떠난 사용자를 생성 작성 폼이 상세로 옮기지 않는다
문제: 생성기 템플릿의 작성 폼은 저장을 기다린 뒤 openSaved에서 상세로
navigate한다. 그 사이 화면이 남아 있는지 보지 않는다. 저장 중에는 이탈 확인이
꺼져 있어 사용자는 목록이나 다른 기능으로 갈 수 있다. 저장이 끝나면 언마운트된
화면의 navigate가 앱을 그 항목의 상세로 옮긴다(데이터 라우터의 navigate는
언마운트 뒤에도 동작한다, 리뷰 probe 08-R7). 다시 돌아온 작성 폼에 입력이
있으면 이유 없는 이탈 확인 창이 뜬다. 참조 폼은 저장 뒤 이동하지 않아 생성기에만
있다.

고른 방법: 생성 페이지가 마운트 여부를 ref로 들고(useEffect에서 true, 정리에서
false), 저장 뒤 상세 이동과 "변경됨으로 확인" 뒤 목록 이동을 마운트된 동안만
한다. 생성 페이지 테스트에 한 행을 더했다: 저장을 붙잡아 둔 채 breadcrumb으로
목록에 가고, 저장을 끝내면 목록이 새 항목을 보이고(목록 무효화) 1초 안에 상세
heading이 오지 않으며 목록 heading이 남는다. 생성기 단위 테스트가 두 조건과 그
행을 NEVER·KEYED 모두에서 본다. 매뉴얼 reference/create-feature.md에 적었다.
버린 대안: 현재 위치가 작성 라우트인지 보기(다시 돌아온 새 인스턴스가 있으면
옛 인스턴스의 이동도 통과한다), 이동 대신 결과를 남겨 보이기(1106/08-01 (2)처럼;
완료 기준은 이동만 요구해 이번에는 넣지 않았다).

위험·한계: 떠난 뒤 끝난 저장은 다시 돌아온 작성 폼에 결과를 보이지 않는다(참조
폼의 목록 안내는 생성기에 없다). 생성 페이지 테스트의 새 행은 녹색일 때 1초를
기다린다(상세가 오지 않음을 보는 음성 확인). repo 안에 생성 결과 파일은 없다
(src/features/.generated 없음). 이미 생성한 기능에는 반영되지 않는다.

검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/unit/create-feature.test.ts, corepack pnpm test:feature-scaffold
(FE-GATE-020, 생성 기능 드릴 NEVER·KEYED)

Refs: 1106/08-02
2026-11-06 05:36:06 +09:00
DongHyeonka 757d1c736b fix(a11y)!: 실패 화면으로만 검사한 라우트를 a11y.json에서 통과로 세지 않는다
문제
접근성 e2e는 보호 라우트의 목록 조회에 빈 목록을 답한다. 자원 하나를
읽는 상세 라우트(참조 기능의 상세, 생성기 --with-create의 상세)는
일반 답이 없어 실패 화면에서 axe를 돌린다. 그런데
scripts/write-a11y-report.ts는 설치된 라우트 전체를 scope에 넣고
automatedStatus "passed"를 쓴다. 화면 내용은 한 번도 검사하지 않은
라우트가 통과로 보고된다. annotation은 test 결과에만 남는다.

고른 방법과 버린 대안
- scripts/lib/a11y-data-state.ts(새 파일): 라우트 test가 끝날 때
  자기 상태를 artifacts/tests/a11y-data-state/<ROUTE_ID>.json에 남긴다.
  실패 화면으로만 봤으면 이유를 쓰고, 아니면 지운다. 그래서 라우트마다
  마지막 실행이 정한다. 세 엔진이 같은 파일을 쓰므로 임시 파일에 쓰고
  rename한다.
- tests/e2e/accessibility.spec.ts: 위 기록을 남긴다(공개 라우트와
  데이터 상태로 본 라우트는 지운다).
- a11y.json schemaVersion 2: scope에는 자기 상태로 검사한 라우트만,
  notChecked에는 실패 화면으로만 본 라우트와 이유를 넣는다. 둘을
  합치면 설치된 라우트 레지스트리와 같아야 한다(schema가 본다).
- 상세 라우트를 실제 데이터 상태로 검사하는 안은 버렸다. 출력
  validator에서 유효한 값을 일반적으로 만들 수 없고, 기능마다 견본
  응답을 받는 자리를 새로 열어야 한다.
- annotation을 Playwright JSON reporter로 읽는 안은 버렸다. test:a11y
  스크립트의 reporter와 산출물 경로를 바꿔야 하고, 경로는 다른 작업
  (12-04)이 바꾸는 중이다.
- 매뉴얼(docs/manual/reference/create-feature.md)에 상세 라우트가
  notChecked로 적히고 수동 검토가 맡는다고 적는다.

위험·한계
- a11y.json 모양이 바뀐다(schemaVersion 1 → 2, scope 의미, 새 필드).
  템플릿 안의 소비자는 ci-artifact-validator 하나이고 같이 바꿨다.
- 템플릿 상태에서도 참조 기능의 상세 라우트가 notChecked로 나온다.
  지금까지 실제로 검사하지 않던 것이 드러나는 것이다.
- 기록 디렉터리는 artifacts/tests 아래 고정 경로다. 12-04가 산출물
  경로를 실행마다 나누면 이 경로도 따라가야 한다.
- 라우트 test가 돌지 않은 실행에서는 그 라우트의 지난 기록이 남는다.
  지난 기록이 "검사 안 함"이면 덜 주장하는 쪽이라 위험하지 않다.

검증
- desktop batch에서 확인:
  node scripts/run-vitest.ts run tests/unit/a11y-report.test.ts
  corepack pnpm test:a11y (세 엔진) 뒤 artifacts/tests/a11y.json의
  notChecked에 REFERENCE_RESOURCE_DETAIL이 있고 scope에 없어야 한다.
- RED: 부모 커밋에는 scripts/lib/a11y-data-state.ts가 없어 새 unit
  test 파일 전체가 실패한다.

Refs: 1103/11-01
BREAKING CHANGE: artifacts/tests/a11y.json이 schemaVersion 2가 된다. scope는 실패 화면으로만 본 라우트를 빼고, 그 라우트는 새 notChecked 배열에 { routeId, reason }으로 들어간다. scope를 설치된 라우트 전체로 읽던 도구는 scope와 notChecked를 합쳐 읽는다.
2026-11-06 01:05:22 +09:00
DongHyeonka 799ab7f667 fix(dev): dev manifest를 기능 생성·제거 때 다시 쓰는 커밋 파일로 둔다
문제
c15345c·db5728b·0eba082의 dev 전용 Vite 미들웨어(dev server가 설치된
기능의 contract set으로 manifest를 냄)를 넣은 뒤로, dev server를 쓰는
capability e2e가 "requestfailed:GET:/release-manifest.json:net::ERR_ABORTED"로
떨어졌다. 같은 호스트에서 번갈아 쟀다: 미들웨어 있음 5/30·2/30 실패, 없음
0/30·0/30(부하가 더 높았다). trace에서는 첫 manifest 요청이 200 헤더 뒤
끊기고 65 ms 뒤 두 번째 요청이 성공한다. 원인을 끝까지 좁히지는 못했다.
감시 이벤트(파일 쓰기)를 없애도 같았다.

고른 방법
- 미들웨어를 지운다. dev server는 커밋된 public/release-manifest.json을
  그대로 낸다.
- 그 파일의 contractSet을 설치된 기능으로 다시 쓰는 일을 명시적 단계로
  둔다: `create:feature`가 생성 뒤 scripts/write-dev-release-manifest.ts를
  돌리고, 기능 제거 드릴이 지운 뒤 돌린다. 매뉴얼의 되돌리기·기능 지우기
  절과 errors.md에 같은 명령을 적었다. 레지스트리 기준선과 같은 방식이다.
- tests/unit/dev-release-manifest.test.ts가 커밋된 파일이 설치된 기능의
  contract set과 같은지 보고, 다르면 다시 쓰는 명령을 말한다.
- 함께: vite.config.ts가 artifacts/·dist/·.tmp/를 감시하지 않는다.
  Playwright trace의 .html이 열린 페이지를 모두 다시 불러오게 했다(dev
  server 로그의 page reload).
- 버린 대안: dev 부팅에서 contract set 검사 건너뛰기. 검사하는 테스트와
  같은 조건을 dev만 따로 두게 된다.

위험·한계
- 기능을 손으로 지우고 명령을 잊으면 dev server가 부팅하지 못한다.
  test:unit이 그 상태를 이름과 명령으로 알린다.

검증
- test:unit 2,880건, dev-release-manifest·create-feature 테스트 45건,
  check:types, lint, verify:documentation 통과.
- 생성 기능을 넣은 clone의 dev capability e2e와 merge 단계 14개는 이 커밋
  뒤 깨끗한 clone에서 돈다.

Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.5 14.6 X2 #3, 16-09
2026-11-05 03:30:56 +09:00
DongHyeonka 72b8ab1507 docs(manual): 기능 추가 안내가 초기 JS 기록·로컬 게이트 조건·드릴 범위를 맞게 말한다
문제
매뉴얼만으로 기능을 더한 재실험(리뷰 조치 X2)에서 안내가 틀리거나 빠진
곳이 나왔다.
- 생성 명령 출력과 매뉴얼 01이 초기 JS 기록(config/scale/feature-shape-
  ceilings.json)을 말하지 않는다. 출력은 "baseline does not change"만 적는다.
- 01·create-feature.md가 "드릴은 check:bundle을 돌리지 않는다"고 적는다.
  12-02 뒤로 드릴은 merge 단계 명령으로 check:bundle을 돈다.
- 로컬에서 FE-GATE-013은 VITE_COMMIT_SHA가 40자리 커밋이어야 한다. 실패한
  게이트의 로그 위치가 어디에도 없다.
- 01 6단계가 "생성된 판은 파라미터가 없다"고 적지만 --with-create 상세
  라우트는 codec을 넘긴다. global-ids.md의 API 경로 예가 옛 생성 경로다.

고른 방법
- 생성 명령 Next에 3번(기록 다시 쓰기)과 로그 위치·FE-GATE-013 조건을
  더한다. 매뉴얼 01 "merge 전에 돌릴 것"에 같은 내용과 파일 수 상한을
  적는다. 나머지 문장을 지금 동작에 맞춘다.

검증
- tests/unit/create-feature.test.ts 43건, verify:documentation PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #2 #5 #6
2026-11-05 01:33:38 +09:00
DongHyeonka 41f8801d64 chore(review): 1103 기능 생성기·기능 패턴 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 03-07 09-06 16-01 16-04~16-07

# Conflicts:
#	docs/manual/01-add-a-feature.md
#	docs/manual/reference/create-feature.md
#	docs/manual/reference/patterns.md
#	scripts/create-feature.ts
#	scripts/test-feature-scaffold.ts
2026-11-04 23:49:27 +09:00
DongHyeonka 7411d4a404 test(scaffold): 생성 드릴이 --with-create 쓰기 slice도 만들고 게이트를 돈다
문제
--with-create(NEVER)와 --with-create --keyed(KEYED)가 만드는 코드는 단위
테스트가 텍스트로만 본다. FE-GATE-020의 두 드릴(test:feature-scaffold,
test:sample-removal)은 기본 기능 하나만 만들어 게이트를 돈다. 그래서 쓰기
slice의 타입·lint·테스트·빌드가 머지 게이트에서 깨져도 모른다(16 5.3절의
"생성 결과를 매번 게이트로 돌린다"는 전제).

고른 방법
- scripts/test-feature-scaffold.ts: 기본 기능(scaffold-feature) 옆에
  scaffold-write-feature를 --with-create --keyed로 하나 더 만들고, 둘 다
  만들어졌을 때 같은 게이트를 한 번 돈다. 바꾼 것은 WRITE_FEATURE_ID 상수,
  create-feature-write 검사 한 개, 게이트 조건(created && createdWrite), 머리
  주석이다.
- scripts/test-sample-removal.ts: 참조 기능을 지운 복사본의 create:feature
  인자에 --with-create 한 개를 더했다. 쓰기 slice도 샘플에 기대지 않는다는
  증거다.
- 세 변형(기본, NEVER, KEYED)이 모두 드릴의 게이트를 지난다.
- reference/create-feature.md의 드릴 설명을 맞췄다.

버린 대안
- 드릴 기능 하나를 --with-create로 바꾸기: 기본 변형이 게이트에서 빠진다.

위험·한계
- test:feature-scaffold는 기능 하나만큼(create:feature 한 번과 그 기능의
  테스트) 길어진다. 게이트는 한 번만 돈다.
- 다른 작업(게이트 담당)이 같은 두 파일의 명령 목록을 고칠 수 있다. 내 수정은
  위 줄로 좁혔다.

검증
- flock 아래 CHOKIDAR_USEPOLLING=1 corepack pnpm test:feature-scaffold:
  rc=0, "feature scaffold: PASS (17 checks)" (생성 2 + 게이트 15), 162초.
- 같은 조건 corepack pnpm test:sample-removal: rc=0, "reference-feature
  removal: PASS (23 checks, no fixture IDs)". 참조 기능을 지운 복사본에서
  --with-create 기능을 만든 뒤 scaffold-* 게이트 9개가 모두 통과했다. 첫
  실행은 tests/unit/create-feature.test.ts에 샘플 ID 문자열이 있어
  fixture-id-residue로 실패했고, 그 테스트를 앞 커밋에서 고친 뒤 통과했다.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-06
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-01
2026-11-04 23:47:24 +09:00
DongHyeonka e8c4197e0b test(reference): 참조 context 라우팅 테스트가 참조 기능의 라우트만 본다
문제
`create:feature <id> --context reference-context`로 기능을 참조 context에
넣으면 tests/features/reference-feature/installed-context-routing.test.ts가
실패한다. 그 테스트가 참조 context가 적재하는 라우트 전체를 정확히 비교하기
때문이다. 매뉴얼은 이것을 "못 잡음"으로 두고 참조 context에 넣지 말라고만
적었다(메인 세션 X1).

고른 방법
비교 대상을 참조 기능 계약의 route ID로 거른다. 테스트의 의도(참조 기능
라우트가 공개 URL 그대로 지연 적재된다)는 그대로다. 매뉴얼 01 1단계와
reference/create-feature.md의 한계 문장을 고쳤다. 생성한 context 선언을
실행하는 테스트는 앞 커밋(tests/unit/create-feature.test.ts)에 있다.

버린 대안
- 생성 명령이 reference-context를 거부: 생성기가 샘플 이름을 알게 되고, 테스트
  가정 하나를 지키려고 정상 입력을 막는다.

위험·한계
- 참조 context에 넣은 기능은 경로가 /examples/reference-resources/<base>다.
  참조 기능을 지우면 context가 남아 제거 드릴 잔여 검사에 걸린다고 매뉴얼에
  적었다. 이 경로의 드릴은 돌리지 않았다(추론).

검증
- RED: refx-feature --context reference-context --with-create를 만든 상태에서
  이 테스트가 XONE/REFX 라우트를 받아 실패(앞 커밋 검증 기록). 고친 뒤 같은
  상태에서 tests/features 124건 통과, tests/component·architecture와
  create-feature·schema-metadata-policy 49파일 374건 통과. 생성 기능은 지웠다.
- lint, check:types(test), verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 1101/16-02
2026-11-04 23:42:06 +09:00
DongHyeonka 2ec9d56008 feat(scaffold): create:feature --with-create가 짝 백엔드 생성기와 같은 slice를 만든다
문제
- 프론트 create:feature는 GET /api/<base>-items 목록 하나를 만든다. 짝 백엔드
  new-feature.sh는 POST /<plural>(201, NOT_IDEMPOTENT)과 GET /<plural>/{id}를
  만든다. 경로 규칙도, operation 쌍도 맞지 않는다(03-07).
- 짝 백엔드 모양(Envelope)의 상세 GET·작성 POST·폼·결과 불명 화면 예제는
  참조 기능뿐이고, 참조 기능은 problem details 모양이라 옮기면 짝 백엔드에서
  쓰이지 않는 분기와 값(400·422 분류, retryBudget 0, Envelope 줄 없음)을
  함께 옮긴다(09-06, 16 5.3절).
- 생성된 목록의 "총 N개"는 배열 길이다. 백엔드 meta.page.total을 쓰지
  않는다(03-02 수정이 남긴 일).

고른 방법
- 경로: 백엔드 new-feature.sh와 같은 복수형 규칙(backendPathSegment)으로
  API_PATH 상수 하나를 둔다. 백엔드 api-base-path는 API_BASE_URL에 붙인다.
- 목록: mapper가 { items, total }을 내고 total은 page?.total ?? 길이다. 빈
  목록은 EmptySurface로 같은 빈 상태를 그린다.
- --with-create: 상세 GET, 작성 POST, 상세·작성 라우트와 페이지, 폼 스키마
  (이름 100자 = 백엔드 NAME_MAX_LENGTH), 뮤테이션 정책(commandMutationIdentity),
  작성 폼 테스트를 만든다. 작성은 백엔드 기본에 맞춰 NEVER(retryBudget 0, 키
  없음)다. --keyed는 백엔드 create를 IdempotencyExecutor 뒤에 둔 경우의
  KEYED 값(IDEMPOTENCY_REPLAY, retryBudget 1)을 쓴다.
- 작성 descriptor: acceptedStatuses [201], refusedBeforeWrite
  ["<BASE>_INVALID"], classifyStatus는 401·403·429를 NOT_APPLIED(백엔드
  보안 필터·@RequiresPermission 프록시·rate-limit interceptor가 use case 전에
  거절한다). mapProblem이 <BASE>_INVALID를 이름 칸 오류로 바꾼다.
- 생성 테스트: gateway 테스트가 세 operation의 백엔드 본문(201 Envelope,
  404 <BASE>_NOT_FOUND, 400 <BASE>_INVALID → NOT_APPLIED, 응답 유실 →
  MAYBE_APPLIED, NEVER는 키 없음·KEYED는 503 IDEMPOTENCY_UNAVAILABLE 뒤 같은 키
  1회 재전송)을 손으로 적는다. 하네스 재시도 상한은 앱 기본값 2다(16-07 (3)).
  작성 폼 테스트는 라우터를 거쳐 201 저장 뒤 상세 열기, 400 거절을 이름 칸에
  보이고 저장 버튼이 켜진 채 다시 저장, 응답 유실 뒤 결과 불명(NEVER는 다시
  보내기 없음, KEYED는 같은 Idempotency-Key로 다시 보내기)을 본다.
- 페이지 테스트의 앱 조립은 <base>-test-app.tsx 하나로 모은다.
- slice 템플릿은 scripts/create-feature-write-slice.ts에 둔다. 리뷰 5.3절
  재검토 조건(템플릿 2,000줄)을 넘지 않게 하고, create-feature.ts의 수정을
  필요한 자리로 좁힌다.
- X1: 생성한 context 선언을 임시 폴더에 써서 생성기 선언 읽기로 읽고, 그
  모듈을 import해 앱 모듈 조립(라우트 루트 검사)이 기능 라우트를 받는지 보는
  단위 테스트를 더한다.

버린 대안
- 작성을 기본 KEYED로: 백엔드 생성 create는 키를 읽지 않아, 같은 키 재전송이
  새 항목을 만든다. 안전해 보이는 거짓 보장이다.
- 참조 기능을 Envelope로 옮기기(09-06 (2)): 참조 테스트와 MSW fixture를 다수
  바꾸고 problem details 예제가 사라진다.
- 목록 값을 배열로 두고 total을 배열 속성으로 싣기: TanStack 구조 공유가 배열
  속성을 버린다.

위험·한계
- 백엔드 생성기는 목록 엔드포인트를 만들지 않는다. 백엔드에 GET 페이지 목록을
  더하기 전에는 생성 목록이 405를 받는다. descriptor 주석과 매뉴얼에 적었다.
- 생성 기능의 초기 JS: 기본 +647 B, --with-create +964 B(이 브랜치 기준선
  203,702 B에서 잰 값, 기능당 1 KiB 안). 기준선의 남은 여유는 1,098 B라
  --with-create 기능 하나를 넣으면 134 B가 남는다.
- 두 생성기를 실제로 띄워 붙여 보지는 않았다. 백엔드 템플릿의 응답 본문과
  경로를 읽어 생성 테스트에 옮겼다.

검증
- RED: tests/unit/create-feature.test.ts 새 17건 실패 → GREEN 43건 통과.
- 기본·--with-create·--with-create --keyed·--context reference-context
  --with-create 네 기능을 만든 상태에서: check:types(app·test·node), lint,
  check:registries(additive), check:i18n, check:architecture,
  check:design-system, check:diagnostics, verify:documentation 통과. 생성 기능
  테스트 77건 통과. 빠른 계층 313파일 3,818건 중 참조 라우팅 테스트 1건만
  실패(X1, 다음 커밋).
- 변이: refusedBeforeWrite 삭제 → gateway·폼 테스트 2건 실패. 상세 GET의
  responseEnvelope 삭제 → 조립 거절로 테스트와 check:registries 실패. KEYED
  retryBudget 0 → 503 재전송 테스트 실패. 정책의 descriptor 상수 오타 → tsc 실패.
- flock 아래 build, check:bundle: 기준 203,702, 기본 기능 204,349, --with-create
  기능 204,666 / 204,800 B PASS.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-06
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-07
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-01
2026-11-04 23:42:00 +09:00
DongHyeonka fbd8f7d148 chore(review): 1103 게이트·드릴 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 02-06 11-06 12-09 10-01 11-03~11-05 12-02 12-04 12-05 12-08 14-04 16-02

# Conflicts:
#	docs/manual/01-add-a-feature.md
#	docs/manual/02-decision-tables.md
#	docs/manual/reference/patterns.md
2026-11-04 23:08:05 +09:00
DongHyeonka 83f4dd5f8e chore(review): 1103 예제 화면·시각·접근성 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 09-04 15-01 12-01 11-01 16-03 11-02

# Conflicts:
#	docs/architecture/frontend-application-foundation.md
#	docs/architecture/starter-experience.md
#	docs/manual/03-outside-feature-folder.md
#	tests/unit/runtime-adapters.test.ts
2026-11-04 23:04:17 +09:00
DongHyeonka 7f633106bb test(a11y): 접근성 e2e가 기능 API를 descriptor 모양의 빈 목록으로 답한다
문제
tests/e2e/accessibility.spec.ts는 보호 라우트의 모든 API에 맨 배열
`[]`를 답했다. create:feature가 만드는 기능은 responseEnvelope:
"ENVELOPE_V1"이라 `[]`는 ENVELOPE_MISMATCH가 되고, 페이지는 경고 상자를
그린다. spec은 h1과 axe만 봐서 오류 화면을 검사하고도 통과했고, 증거는
그 라우트를 "passed"로 적었다. 경로 파라미터는 `:resourceId`만 바꿔서
다른 이름을 쓰는 기능은 이 템플릿 파일을 고쳐야 했다.

고른 방법 (결정 D4 (b))
- tests/e2e/support/installed-api-answers.ts가 요청을 설치된 GET
  descriptor에서 method와 pathTemplate으로 찾는다. 출력 스키마가 빈
  목록을 받으면 그 operation의 모양으로 답한다(Envelope면 MSW 시나리오와
  같은 successEnvelope, 아니면 맨 배열).
- 목록만 읽은 라우트는 로딩이 끝난 뒤 경고 상자(role="alert")가 없다고
  단언한다. 모양이 다시 어긋나면 axe 통과 대신 여기서 실패한다.
- 경로 파라미터는 이름과 상관없이 모두 a11y-1로 바꾼다. 기능을 더해도
  spec을 고치지 않는다(16-03 앞 절반).
- 설치된 GET이 아닌 요청, 빈 목록을 받지 않는 파라미터 없는 GET은
  501로 답하고 그 목록이 비어 있다고 단언한다.
- 매뉴얼 01·03, starter-experience, create-feature 참조, 수동 점검
  문서의 "모든 API에 []", ".replace를 잇는다" 문장을 동작에 맞췄다.
- 버린 대안: 전역 Envelope 응답(참조 기능 DTO가 거꾸로 깨짐), 기능마다
  접근성 spec 생성(파일·실행 시간 증가).

위험·한계
- 한 자원을 읽는 GET(상세 페이지)에는 빈 목록 말고 줄 본문이 없다.
  그 라우트는 지금처럼 실패 상태로 검사하고 a11y-data-state
  annotation만 남긴다. 경고 상자 단언은 그 라우트에서 건너뛴다.
- write-a11y-report.ts의 증거는 annotation을 읽지 않는다. 상세 라우트도
  "passed"로 적힌다.

검증
- 새 unit 테스트 6건: helper가 없을 때 실패, 추가 뒤 통과.
- 템플릿 상태 chromium test:a11y 대상 spec 14건 통과.
- create:feature sample-feature 상태에서 `@a11y /sample` 세 엔진 통과.
  변이 1(Envelope 대신 맨 배열): 세 엔진 모두 경고 상자 단언으로 실패.
  변이 2(빈·성공 상태에서만 보이는 이름 없는 버튼): 세 엔진 모두
  axe button-name으로 실패. 생성 파일은 지웠다.
- check:types:test, eslint, verify:documentation, check:ci 통과.

Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 11-01
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-03
2026-11-04 22:59:03 +09:00
DongHyeonka e1b4e2880d fix(scaffold): 기능 생성 드릴이 merge 단계 명령을 gates.json에서 뽑아 돈다
문제
create:feature는 "모든 merge 게이트를 통과하는 가장 작은 기능"을 만든다고
적고, test:feature-scaffold(FE-GATE-020)가 그 주장을 지키는 유일한 드릴이다.
그런데 드릴은 손으로 적은 15개 명령만 돌았고 merge 단계는 명령 참조가
88개다. 그 범위 밖(시각 회귀, a11y, 번들, 계약·스키마·시나리오 테스트 등)에서
생성 기능을 깨는 템플릿 변경이 생겨도 FE-GATE-020은 통과했다(12-01·12-03이
실제로 그렇게 생겼다). 또 제품 기능 제거 드릴
(test:sample-removal -- --feature=<id>)은 어떤 게이트도 돌지 않아, 빈 사유
결함(16-02)이 드러나지 않았다.

고른 방법
- 새 scripts/lib/feature-scaffold-drill.ts가 fixture의 config/ci/gates.json
  merge 단계를 단계 순서대로, 명령마다 한 번 뽑는다. 음성 fixture 명령은
  run-ci-gate.ts처럼 등록된 종료 코드와 진단 ID로 판정한다.
- 돌지 않는 명령은 SCAFFOLD_DRILL_EXCLUDED_SCRIPTS에 이유와 함께 둔다:
  브라우저 명령 7개(FE-GATE-020 job에 브라우저가 없다. merge_gate matrix
  browser: false), test:system(bubblewrap·systemd·cgroup 필요, 기능과 무관한
  provider 샌드박스 검사), verify:lockfile(연결한 node_modules에 install한다),
  제거 드릴 5개(저장소를 다시 복사한다. 이 드릴 자신 포함). merge 단계에 없는
  스크립트를 제외 목록에 두면 실패한다.
- 생성 기능을 merge 명령 뒤에 test:sample-removal -- --feature=scaffold-feature로
  다시 지운다(16-02 둘째 절반).
- 생성 명령의 주석·Next 출력과 매뉴얼 두 곳의 주장을 실제 범위로 고쳤다.
- 버린 대안: 손 목록에 빠진 명령 더하기. 다음 merge 명령이 다시 빠진다. 복사본
  에서 브라우저 게이트까지 전부(리뷰 5.1 (d)). 드릴 job에 브라우저가 없고 수십
  분이 든다. 생성 경로만 도는 chromium a11y·시각 1회(5.1 (c)). 12-01·12-03을
  고치는 다른 작업이 진행 중이라 지금 넣으면 그 수정 전까지 드릴이 실패한다.
  그 둘이 들어오면 제외 목록에서 빼는 것을 다시 본다.

위험·한계
- 드릴 시간이 크게 는다(빌드·release candidate·coverage·제거 드릴 한 번).
  FE-GATE-020 job(45분)의 임계 경로를 넘으면 리뷰 5.1 재검토 조건대로 줄인다.
  tests/unit이 한 merge에서 도는 횟수(1101/10-06)도 는다.
- 이 커밋 메시지에는 드릴 전체 실행 결과를 적지 않았다(공유 잠금 대기).

검증
- RED: 새 tests/unit/feature-scaffold-drill.test.ts의 "is what
  test:feature-scaffold runs"가 수정 전 실패.
- 수정 뒤 feature-scaffold-drill 5건(merge 명령 전부가 실행 또는 제외, 음성
  fixture 기대 유지, merge 단계에 명령을 더하면 드릴이 돈다, 낡은 제외 거부,
  드릴이 이 목록을 씀), create-feature, removal-fixture 합계 43건 통과.
  verify:documentation PASS_SCOPED, check:types 통과, eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-02
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-02
2026-11-04 21:20:04 +09:00
DongHyeonka c4d587052e fix(removal): 참조 기능을 지워도 문서 게이트가 통과하고 드릴이 그것을 본다
문제
README는 참조 기능을 지울 수 있다고 적는다. 그러나 매뉴얼·입구 문서
10개가 참조 기능과 그 드릴 전용 파일의 경로를 백틱으로 적고,
verify:documentation(FE-GATE-017)은 백틱 경로의 존재를 검사한다. 그래서
참조 기능을 지운 복사본에서 문서 게이트가 경로 24개로 실패한다. 제거
드릴(test:sample-removal)은 문서를 복사하지 않고 그 게이트와 lint·
check:i18n·check:design-system을 돌리지 않아 이 충돌을 보지 못했다.

고른 방법
- 리뷰 5.2절 (b): 참조 기능이 가진 경로는 백틱 없이 "예제(참조 기능)"으로
  적는다. 기능 공통 모양은 생성 경로 꼴(`src/features/<id>/domain`)로
  적는다. 규칙은 docs/manual/reference/patterns.md 첫머리에 적었다.
- 드릴은 REMOVAL_FIXTURE_DOCUMENT_TARGETS(README·CHANGELOG·docs)까지
  복사하고, 지운 뒤와 생성 기능을 더한 뒤 두 번 모두 lint,
  verify:documentation, check:i18n, check:design-system을 돈다
  (FOLLOW-UP 09-07). 문서 테스트 두 개도 fixture에서 다시 돈다.
- 버린 대안: 검사기가 참조 기능 경로를 "없어도 되는 경로"로 보기(5.2
  (c)). 매뉴얼이 없는 파일을 가리키는 상태를 허용한다. 참조 기능을 지울
  수 없게 하기(5.2 (d)). README 약속과 드릴의 존재 이유가 바뀐다.

위험·한계
- 템플릿 자신에서도 참조 기능 경로의 존재를 문서 검사가 더는 보지
  않는다. 참조 기능 파일 이름을 바꾸면 그 문장은 사람이 고쳐야 한다.
- 드릴 시간이 lint·문서 검사 두 번만큼 는다.
- 드릴 실제 실행 결과는 이 커밋 메시지에 적지 않았다(공유 잠금 대기).

검증
- 참조 기능·참조 context·SAMPLE_EXTRAS를 지운 복사본(scratchpad
  sim-sample-docs.sh)에서 수정 전 FAIL_UNVERIFIED(문서 10개), 수정 뒤
  PASS_SCOPED.
- 저장소에서 verify:documentation PASS_SCOPED,
  documentation-readiness 14건 통과, eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04
2026-11-04 21:02:14 +09:00
DongHyeonka 245f428123 fix(features): 제품 capability 타입과 기본값 설정 키가 타입 검사 3종을 통과한다 (1103/09-02)
문제
제품 확장 지점이 실행 경로에서는 동작했지만 타입 검사 경로에서 막혔다.
(a) 문서대로 product-composition.ts에서 FeaturePlatformCapabilities를
보강하면 check:types:node가 실패했다. scripts 프로그램은 기능 코드를 끌어오지만
product-composition.ts는 끌어오지 않아 보강이 보이지 않았고, 오류는 기능
파일을 가리켰다. (b) 기본값 있는 제품 설정 키(.default()) 하나가 RuntimeConfig를
리터럴로 쓰는 템플릿 테스트 7개 파일의 타입을 깼다. 픽스처는 vi.mock이라 이
경로를 지나지 않았다.

고른 방법
- 제품 소유 빈 파일 src/features/product-capabilities.ts를 두고
  FeaturePlatformCapabilities가 그 ProductFeaturePlatformCapabilities를
  extends한다. feature-adapter-contribution.ts가 import하므로 기능을 보는 모든
  프로그램에 들어간다. 문서만 "기능 파일 안에서 보강"으로 고치는 최소안은
  capability 하나를 여러 기능이 쓸 때 보강 위치가 갈려 버렸다. 기존 제품 소유
  파일에 칸을 더하지 않고 새 파일로 둔 이유: 템플릿은 복사 뒤 제품 소유 파일을
  고치지 않으므로, 새 파일이어야 동기화 때 충돌 없이 들어간다.
- tests/helpers/runtime-config.ts의 testRuntimeConfig: 템플릿 키는 테스트가
  쓰고, 제품 키는 실제 스키마(validateRuntimeConfig)로 기본값을 채운다. 템플릿
  테스트 6개 파일이 이것을 쓰고, release-coherence는 문서 타입을 z.input으로
  바꿨다. 제품 키를 모두 Partial로 하는 대안은 기본값 키에도 undefined 처리를
  강요해 버렸다.
- tests/unit/product-extension-typecheck.test.ts: 복사본에 제품 소유 파일 세 개와
  기능 하나를 실제 파일로 채우고 tsc app·node·test를 돈다.
- 문서: starter-experience 표, 매뉴얼 01·03·patterns·create-feature,
  frontend-application-foundation, 계약 주석.

위험·한계
- 기본값 없는 필수 제품 키는 여전히 템플릿 테스트에서 실패한다(이제 타입이
  아니라 helper가 이유를 적고 throw). 문서에 ".default() 또는 .optional()"을
  적었다.
- product-composition.ts 안에서 이미 보강한 다운스트림은 보강을 새 파일로
  옮겨야 node 검사가 통과한다.

검증
- RED: 새 typecheck 테스트가 수정 전 app·node(보강 미연결)와 test(템플릿
  테스트 8건, E-PROD와 같은 위치)에서 실패.
- 수정 후 그 테스트와 영향받는 9개 테스트 파일 → 10 files / 83 tests 통과.
- check:types(tsc app·node·test), check:architecture, eslint,
  verify:documentation PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-02
2026-11-04 20:30:47 +09:00
DongHyeonka 12f3bb7862 refactor(contracts)!: V2 API 행을 지우고 FE-REG-API를 HTTP descriptor에서 뽑는다
문제
기능 하나가 같은 HTTP API를 두 번 적는다. *-api-contract.ts의 V2 행
(defineRestOperation)은 check:registries(FE-REG-API)가 검사하는 선언이고,
contract contribution의 V3 descriptor가 실제로 실행된다. 둘이 어긋나지 않게
http-operation-v2-v3-parity 테스트를 따로 둔다. 048f490으로 V2 클라이언트가
없어져 V2 행을 읽는 실행 코드는 없고, 검사만 남은 두 번째 사본이다. V2 행을
위한 기능별 runtimeSchemas·mappers 레지스트리와 V2 보안 프로필 해석
(resolveRestSecurityProfiles)도 같이 남아 있다. 사용자 지시: 최신 경로 하나만
남기고, 레지스트리 기준선 재승인을 승인했다.

고른 방법
- src/contracts/api-operations.ts를 projectApiOperationRows 하나로 바꿨다.
  조립된 contribution의 descriptor마다 operationId, featureId, method, path,
  authProfileId, retrySemantics, requestBody, responseBody, responseEnvelope,
  request/response/problemSchema(검증기 schemaId) 행을 만든다. FE-REG-API는
  같은 export(API_OPERATIONS)를 읽고, governance 정의를 이 필드로 바꿨다.
  requestSchema·responseSchema는 그대로 FE-REG-SCHEMA를 참조한다.
- FeatureRuntime은 apiContract 대신 schemas(FE-REG-SCHEMA 행)만 받는다.
  installed-feature-runtime-registries는 schemas로 스키마 레지스트리를 만들고
  FE-REG-API 행을 descriptor에서 뽑는다. RUNTIME_SCHEMA_CODECS, MAPPER_REGISTRY,
  REST_PROFILE_BINDINGS_VALID, API_RUNTIME_BINDINGS_VALID를 지웠다.
- realtime snapshot 바인딩은 ApiOperationRow를 받고 method GET과
  retrySemantics SAFE·IDEMPOTENT를 본다(V2의 contractVersion·semantics·
  replayPolicy 대신).
- rest-profiles.ts에서 V2 행용 provider·CSRF 프로필 해석을 지웠다. V3는 조립
  때 auth profile을 검사하고 자격증명 헤더를 프로필로 거른다.
- 참조 기능: reference-api-contract.ts를 reference-schema-metadata.ts로
  바꾸고(스키마 행만), V2 runtime codec·operation mapper·레지스트리 mapper를
  지웠다. V3 descriptor가 쓰지 않는 NoRequest 스키마 행도 지웠다.
- create:feature: <base>-api-contract.ts 대신 <base>-schema-metadata.ts를
  만든다. codec·mapper 레지스트리 행과 그 테스트를 만들지 않는다.
- 레지스트리 기준선을 update:registry-baseline으로 다시 만들고 승인했다
  (digest 16f72742…, 승인자 DongHyeonka, 이유에 사용자 승인을 적음).
- 매뉴얼 01·02·reference, starter-experience, 계약 문서의 V2 설명을 지웠다.

버린 대안
- V2 행을 남기고 V3에서 생성하기: 생성 단계와 생성물이 하나 더 생긴다. 행은
  실행되지 않으므로 메모리에서 뽑아 검사하면 충분하다.
- 스키마 메타데이터(FE-REG-SCHEMA 행)도 검증기에서 뽑기: boundary·
  unknownFieldPolicy·owner는 검증기에 없고, 라우트 스키마도 같은 레지스트리를
  쓴다. 이 행은 V2가 아니라 스키마 레지스트리라 남겼다.

위험·한계
- BREAKING: FeatureRuntime 모양, contracts·rest-profiles·loaded-feature-runtimes
  의 이름이 바뀌거나 없어졌다. memento-frontend의 memento-web이 V2 행을 쓴다.
  옮기는 법은 CHANGELOG에 적는다.
- V2 보안 프로필 일관성 검사(auth "none"과 ANONYMOUS, 쿠키 프로필의 CSRF
  모드)가 사라졌다. V3 descriptor에는 그 칸이 없다.
- BoundedPollOperationContract(realtime polling recipe)는 contractVersion: 2
  필드를 갖지만 자체 계약이라 바꾸지 않았다.

검증
- check:types, lint, check:architecture, check:registries(11 registries PASS,
  compatibility=none), check:ci, check:diagnostics, check:adapter-inventory,
  verify:documentation 통과.
- test:unit 2,566(새 tests/unit/api-operation-rows.test.ts 3건 포함),
  test:integration 114, test:component 245, test:contract 23,
  test:runtime-schema 56, tests/features 99 통과.
- tests/unit/second-api-feature-registries.test.ts: V3 descriptor만 가진 두
  번째 기능을 복사본에 넣으면 기준선을 고치지 않고 check:registries가 통과한다.
- check:bundle 통과. 초기 JS 201,598 → 200,911 B.
- test:feature-scaffold 16개, test:sample-removal 23개 검사 통과.

BREAKING CHANGE: FeatureRuntime이 apiContract 대신 schemas를 받는다.
defineRestOperation, ApiOperation, RestOperationV2, composeApiOperations,
validateApiRuntimeBindings, getApiOperation, contracts의 API_OPERATIONS,
createRestProviderProfile, RestProviderProfile, resolveRestSecurityProfiles,
validateRestProfileBindings, REST_CSRF_PROFILES, RestCsrfProfile,
loaded-feature-runtimes의 RUNTIME_SCHEMA_CODECS, MAPPER_REGISTRY,
REST_PROFILE_BINDINGS_VALID, API_RUNTIME_BINDINGS_VALID가 없어졌다. 기능은
operation을 contract contribution에만 적고, schemas 행을 feature-runtime에
넘긴다.
2026-11-03 21:37:48 +09:00
DongHyeonka 8b2048763b docs(manual): 새 기능 추가 매뉴얼을 docs/manual에 쓴다 (U9, 1101/16-01)
문제
- 새 기능을 추가하는 절차가 starter-experience.md의 영어 단계 7개와
  폴더 밖 파일 표뿐이다. 무엇을 고르는지(context, 계약 출처, 재시도 의미,
  결과 불명, 인증, 페이지 템플릿), 어느 검사가 무엇을 못 잡는지, 실패
  메시지가 어느 파일을 가리키는지는 리뷰 문서(16 영역 8절)에만 있다.
  리뷰 문서는 복사한 프로젝트가 지울 수 있는 작업 이력이다.
- create:feature(U7)가 생겼지만 그 인자, 만드는 파일, 사람이 해야 하는 일
  (a11y 서명, 자리표시자 계약 신원 교체)을 설명하는 문서가 없다.

고른 방법
- docs/manual/을 한국어로 쓴다(결정 5). README(독자, 읽는 순서, 두는 것과
  안 두는 것), 01 작업 순서 0~11단계, 02 결정표 6개, 03 기능 폴더 밖 파일,
  reference/ 4개(create-feature, global-ids, patterns, errors).
- 01은 1단계에서 create:feature로 시작하는 길을 기본으로 두고, 단계마다
  정할 것, 기준, 잡는 검사(명령·게이트 ID·메시지)와 못 잡는 것, 쓸 스킬을
  적는다. 리뷰 시점의 "못 잡음"은 지금 코드로 다시 확인해 고쳤다(예: 루트
  밖 라우트는 이제 앱 모듈이 적재 때 거부한다).
- 실패 메시지는 src·scripts의 문자열을 그대로 옮기고 값 자리만 <...>로
  바꿨다.
- 목록 대신 정본 위치를 적는다(공통 원칙 8). route ID는 ROUTE_REGISTRY,
  게이트는 config/ci/gates.json, 백엔드 멱등성 응답은 백엔드 템플릿
  docs/web/http-contract.md §2를 가리키고 표를 옮기지 않는다. 공통 원칙은
  design-docs의 conventions/feature-design-principles.md를 번호로만
  가리킨다.
- 03은 starter-experience.md의 폴더 밖 표를 정본으로 링크하고 복사하지
  않는다. 생성 명령이 하는 것 / 사람이 꼭 하는 것 / 조건부 / 고치지 않는
  것으로 나누고, 표에 없는 절차(a11y 서명, 자리표시자 교체, 기능 삭제)만
  더한다.
- 16 영역 8.4의 금지 목록(목표 디렉터리 구조 절, 예전 폴더 밖 표, 참조
  페이지의 경로 문자열)은 링크하지 않고 README에 그 이유를 적는다.
- 버린 대안: 리뷰 8절을 그대로 옮기기(리뷰 시점 사실이 지금 코드와 다르고
  지울 수 있는 이력에 기댄다), starter-experience.md에 한국어 절을 더하기
  (입구 문서는 영어이고 다른 에이전트 소유다), 실패 메시지를 요약해 쓰기
  (메시지로 문서를 검색할 수 없다).

위험·한계
- docs/README.md §1 링크는 넣지 않았다(오케스트레이터 몫). 링크하기 전에는
  verify:documentation이 이 폴더를 검사하지 않는다. 폴더 링크는 바로 아래
  .md만 검사하므로 reference/도 따로 링크해야 한다.
- 플랫폼 규칙 근거는 다른 에이전트가 옮기는 scale-architecture.md를 절
  번호로 가리킨다. 이 커밋에는 그 파일이 없어 링크 대신 백틱 이름으로 썼다.
- 매뉴얼로 막을 수 없는 것이 남는다. 기능 전용 e2e spec은 tests/e2e에만
  둘 수 있어 기능 폴더 밖이다. --context reference-context는 참조 기능
  테스트 하나를 깨뜨린다. 생성 드릴은 check:bundle을 돌리지 않는다.
- "실험 E를 매뉴얼만 보고 다시 하기"는 문서로만 점검했고 실제로 다시
  돌리지 않았다.

검증
- docs/README.md §1에 manual/, manual/reference/ 링크를 임시로 넣고
  node scripts/verify-documentation-readiness.ts: PASS_SCOPED. 7개 문서
  모두 missingPaths·missingScripts·unknownGateIds 0. 임시 링크는 되돌렸다.
- 변이: patterns.md에 없는 경로·script·게이트 ID를 넣으면 세 항목을 모두
  말하며 FAIL_UNVERIFIED.
- 메시지 대조 스크립트: 백틱 안 148개 문구 중 106개는 코드에 그대로 있고,
  42개는 코드가 조각을 이어 만드는 문구(접두어·필드 이름·값 채움)라 하나씩
  코드에서 확인했다.
- node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts
  tests/unit/deletable-history-documents.test.ts
  tests/unit/repository-file-inventory.test.ts: 3파일 38건 통과.
2026-11-03 07:27:36 +09:00