Commit Graph
11 Commits
Author SHA1 Message Date
DongHyeonka 2017ef76ff fix(query): 키 없는 결과 불명 요청에는 재전송을 주지 않는다
문제
resendUnknownEffect는 가장 오래된 admission이 UNKNOWN이고 intent가 있는지만
본다. 키 없는 명령(NEVER)도 intent는 있다. 그래서 응답을 잃은 NEVER 쓰기의
결과 불명 화면에서 "같은 요청으로 다시 보내기"를 누르면 키 없이 다시 나가고,
서버가 두 요청을 가려낼 수 없어 같은 항목이 두 번 생길 수 있다(리뷰 실험
X-D: fetch 2회, 키 [null, null]). 짝 백엔드 생성 기능의 create가
NOT_IDEMPOTENT이고 매뉴얼이 "모르면 NEVER"를 권하므로 이것이 짝 사용의
기본 경로다. 화면(AsyncSurface)은 콜백이 있으면 버튼을 그린다. 훅에도 화면에도
이 버튼을 숨기는 장치가 없다.

고른 방법
- application-query.ts canResend: head가 UNKNOWN이고 intent에
  idempotencyKey가 있고 reconciliation 중이 아닐 때만 참. resendUnknownEffect는
  거짓이면 null을 돌려준다. 컨트롤러가 canResendUnknownEffect로 같은 값을 낸다.
- AsyncState에 선택 칸 unknownEffectResendable(결과 불명일 때만)을 두고,
  훅이 deriveAsyncState 신호로 채운다. AsyncSurface는 이 값이 false면
  onResendUnknownEffect가 있어도 재전송 버튼을 그리지 않는다. 그래서 기존
  페이지 배선(참조 폼)은 바꾸지 않아도 키 없는 명령에서 버튼이 사라진다.
- KEYED는 지금처럼 같은 키로 재전송한다.

버린 대안
- 페이지가 canResendUnknownEffect를 보고 콜백을 넘기지 않게만 하기: 기존
  배선을 복사한 다운스트림 페이지에 버튼이 남는다(누르면 아무 일도 없다).
- AsyncSurface에 별도 prop: 같은 사실을 페이지가 한 번 더 옮겨야 한다.

위험·한계
- 키 없는 결과 불명 화면에는 "변경됨으로 확인"과 목록 새로고침만 남는다.
  "적용 안 됨"으로 닫는 길은 없다(근거 없는 확정을 주지 않는 기존 결정).
- 같은 입력으로 submit을 다시 부르는 경로(D-1 replay)는 바꾸지 않았다. 폼은
  결과 불명 동안 제출을 막는다.
- hand-built AsyncState(칸 없음)는 지금처럼 버튼을 그린다.

검증
- RED: application-mutation-admission 2건(NEVER: canResend false·resend null·
  execute 1회, KEYED: canResend true), async-surface 2건 실패.
- GREEN: tests/unit·integration·component·features·contract 250파일
  3,147건 통과. 변이(훅이 키를 보지 않음, 화면이 칸을 보지 않음) 모두 검출.
- check:types, lint, check:architecture, verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 0929/03-03
Refs: docs/reviews/2026-11-03-maturity-review/README.md 2.1
2026-11-04 20:43:06 +09:00
DongHyeonka 1e8b3d049f feat(http): operation이 쓰기 전 업무 거절 code를 선언한다
문제
Envelope operation의 400·409·422는 백엔드 표의 세 code만 NOT_APPLIED이고
나머지는 모두 MAYBE_APPLIED다. 기능의 classifyProblem은 이를 바꿀 수 없다.
짝 백엔드 생성 기능의 create는 이름 규칙을 트랜잭션 전에 검사하고 400
<FEATURE>_INVALID를 준다. 그런데 폼은 "변경 결과를 확인할 수 없습니다"를
띄우고 저장 버튼을 끈다. 입력을 고쳐도 다시 저장할 수 없다(리뷰 실험
X-A·X-B). 401·403·429는 classifyStatus로 operation이 정할 수 있는데
400·409·422는 정할 자리가 없다.

고른 방법 (결정 D2 ①)
- CommandEffectDescriptor에 선택 칸 refusedBeforeWrite?: readonly string[].
  표 밖 400·409·422가 이 목록의 code면 NOT_APPLIED다. 함수가 아니라 code
  목록이라 리뷰할 수 있고, status 범위를 통째로 NOT_APPLIED로 만들 수 없다.
- 조립 검사(assertRefusedBeforeWrite): 목록은 Envelope operation에만,
  code는 백엔드 문법, 중복 금지. IDEMPOTENT_*·IDEMPOTENCY_*는 거절한다
  (409 IDEMPOTENT_IN_FLIGHT의 앞선 요청은 적용될 수 있다).
- 실행기도 같은 code와 표의 code(VALIDATION_FAILED 등)를 무시한다. 조립
  없이 실행기를 부르는 경로의 fail-close다.
- 조립이 목록을 얼려 복사한다(LIVE-03). classifier는 지금처럼 참조로
  두고, 설치본이 원본을 prototype으로 물려받아 classifier의 this가 그대로다.
- 매뉴얼 02 4절과 계약 문서 6.1절에 언제 적고 언제 적지 않는지,
  <FEATURE>_INVALID 예와 거부 문구를 적었다.

버린 대안
- 표 밖 400 전체를 NOT_APPLIED: BAD_PARAMETER·MAPPING_FAILED는 쓰기 뒤에도
  나온다.
- 분류기 판정 복원: 3261208이 버린 길. 400 전체를 NOT_APPLIED로 보는
  분류기가 키 보호를 푼다.
- 결과 불명 화면에 "적용되지 않음" 버튼: 사용자가 모르고 누르면 새 키로
  중복이 생긴다.
- 백엔드 단계 신호(error.applied): 두 repo 계약 변경이다(D2 ②).

위험·한계
- 쓰기 뒤에도 나오는 code를 잘못 적으면 결과 불명 요청이 새 키로 나가
  중복이 생길 수 있다. 책임은 선언한 기능 작성자에게 간다. 매뉴얼이 백엔드
  코드에서 던지는 곳을 확인한 code만 적으라고 한다.
- 생성기(scripts/create-feature.ts)는 이 칸을 아직 쓰지 않는다. 다른 작업이
  이어 받는다.
- 결과 불명 화면이 거절 code의 문구를 보이는 것(08-01 (가))은 하지 않았다.

검증
- RED: 새 테스트 17건이 이 변경 전 소스에서 실패(조립 규칙 10, 판정 3,
  envelope 통합 3, form-foundation 1).
- GREEN: tests/unit·integration·component·features·contract·runtime-schema
  253파일 3,199건 통과. 폼: WORKLOG_INVALID를 선언하면 결과 unavailable,
  저장 켜짐, 고친 값 저장 fetch 2회, 키 key-1 → key-2. 선언하지 않으면
  effect-unknown, 저장 꺼짐, fetch 1회.
- 변이: 실행기의 멱등성·표 code 무시 제거, 조립의 멱등성 규칙 제거, 목록
  복사 제거, 실행기가 목록을 넘기지 않음 모두 검출. 보존 조건 M5·M10·M24도
  계속 검출.
- check:types, lint, check:registries, check:architecture,
  verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-01
Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-01
2026-11-04 20:38:12 +09:00
DongHyeonka 37615072e9 fix(http): 백엔드가 정한 5xx 결과 불명 답을 분류기와 상관없이 고정한다
문제
Envelope 판정 표가 정하는 5xx는 503 IDEMPOTENCY_UNAVAILABLE 하나다. 짝
백엔드 http-contract.md가 직접 정한 다른 답 셋은 기능의 classifyProblem이
정한다.
- §2 500 IDEMPOTENCY_RECOVERY_REQUIRED: 이전 시도의 효과를 증명할 수 없다.
- §2 503 IDEMPOTENCY_COMPLETION_UNKNOWN(백엔드 bbe944bd): 작업은 돌았고
  결과 기록이 실패했다. 같은 키로 나중에, 새 키 금지.
- §4 503 REQUEST_TIMEOUT: 비동기 요청이 시간을 넘겼고 처리가 계속될 수 있다.
분류기가 5xx를 NOT_APPLIED로 보면 셋 다 SERVER_FAILURE/NOT_APPLIED가 되고,
retryBudget이 있으면 실행기가 다시 보낸다. 폼은 "다시 시도"를 새 키로
연다(리뷰 실험 X-F). 백엔드가 "새 키 금지"라고 한 요청이다.

고른 방법
backend-envelope.ts에 MAYBE_APPLIED_ANSWERS(code → status)를 두고 IU와
같은 줄에 셋을 더했다. status와 code가 함께 맞을 때만 MAYBE_APPLIED다.
MAYBE_APPLIED는 retryHint를 끄므로 자동 재전송이 없고, 코디네이터가 키를
붙들어 결과 불명 화면의 재전송이 같은 키로 나간다. 자동 같은 키 재전송은
지금처럼 KEYED의 503 IU뿐이다.

버린 대안
RECOVERY_REQUIRED에 "재전송 불가" 표시를 실어 화면 버튼을 숨기기(리뷰 최소
개선의 뒷부분): 완료 기준 밖이고 바인딩·코디네이터·화면을 함께 바꾼다.
같은 키 재전송은 백엔드가 다시 실행하지 않고 같은 500이나 재생으로 답한다.
남은 문제로 보고한다.

위험·한계
500 DB_COMPLETION_UNKNOWN(백엔드 error-codes.yaml, http-contract.md 밖)은
넣지 않았다. 계속 분류기가 정한다.

검증
- RED: backend-envelope 단위 3건, envelope 통합 4건(LENIENT 분류기 세 code의
  effect, retryBudget 2에서 fetch 1회·같은 키) 실패.
- GREEN: tests/unit·integration·component·features·contract 250파일
  3,121건 통과. check:types:app·test, eslint, verify:documentation 통과.
- 매뉴얼 02 4절, 계약 문서 6.1절, descriptor 주석에 네 답을 적었다.

Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-04
Refs: docs/reviews/2026-11-03-maturity-review/README.md 10.6
2026-11-04 20:31:08 +09:00
DongHyeonka 61f70cb9b8 fix(contracts)!: 쓰기 operation의 SAFE 재시도 의미를 조립에서 거절한다
문제
설계 정본 8.3은 SAFE를 "GET/HEAD; 보낸 뒤 network 실패에도 재시도 허용"
으로 정한다. 실행기는 그 규칙대로 SAFE면 보낸 뒤 응답을 잃어도 다시
보낸다(http-retry-lifecycle.ts canRetryTransport). 그런데 조립 검사는
쓰기가 SAFE인지 보지 않는다. 생성된 뼈대 descriptor가 GET·SAFE·
retryBudget 2이고, 매뉴얼은 쓰기를 더할 때 이 파일을 고쳐 쓰라고 한다.
retrySemantics를 바꾸지 않으면 POST가 조립을 통과하고, 응답을 잃은 생성
요청이 최대 두 번 더 나간다(리뷰 실험 X-E: fetch 2회, 결과 SUCCESS).
V2에도 이 규칙은 없었다.

고른 방법
assertHttpContract의 쓰기 가지(GET·HEAD 밖)에서 retrySemantics가 SAFE면
operation·method와 고를 값(IDEMPOTENT·KEYED·NEVER), 매뉴얼 절을 담아
거절한다. 매뉴얼 02 3절 "틀리면"에 같은 문장을 더했다.

버린 대안
실행기에서 쓰기의 SAFE를 NEVER처럼 다루기: 잘못 적은 계약이 조용히
다른 뜻으로 돈다. 조립 때 알리는 쪽이 고칠 곳을 바로 보여 준다.

위험·한계
쓰기를 SAFE로 적은 다운스트림은 부팅에서 실패한다. 의도한 실패다.
실행기를 조립 없이 직접 부르는 테스트 경로는 이 검사를 거치지 않는다.

검증
- RED: tests/unit/external-contract-runtime.test.ts의 POST·PUT·PATCH·DELETE
  × SAFE 4건 실패(조립 통과).
- GREEN: 같은 파일 23건 통과. GET·SAFE와 PUT·IDEMPOTENT는 그대로 조립된다.
- tests/unit·integration·contract·features·runtime-schema 214파일 2,904건
  통과. check:types:app·test, eslint, verify:documentation 통과.

BREAKING CHANGE: POST·PUT·PATCH·DELETE operation에 retrySemantics "SAFE"를
쓰면 composeContractContributions가 거절한다. 서버 보장에 맞춰 IDEMPOTENT,
KEYED(commandRecovery 필요) 또는 NEVER(retryBudget 0)로 바꾼다.

Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-03
2026-11-04 20:25:54 +09:00
DongHyeonka c05f41a63e fix(http): KEYED 명령이 백엔드의 실행 전 거절에 같은 키로 다시 보낸다
문제
V2 클라이언트는 보낸 KEYED 요청이 503·408·425·502·504·network·timeout으로
끝나면 같은 키로 자동 재시도했다. 048f490으로 그 동작이 없어졌다. 설계 정본
(2026-07-30 closed deep design 8.3)은 KEYED 자동 재시도를 "known response
status가 retry 가능하다고 package가 명시한 경우만" 허용하고, 응답 없는
network·timeout 뒤에는 금지한다. V2는 응답 없는 실패 뒤에도 보내 정본과
어긋났고, V3는 응답이 재시도를 허락해도 보내지 않아 정본보다 좁았다. 짝
백엔드는 503 IDEMPOTENCY_UNAVAILABLE을 "작업 실행 전에 거부됐다. 같은 키로
나중에 다시 보낸다"로 정한다(http-contract.md §2).

고른 방법
- backend-envelope.ts의 invitesKeyedResend: 503 + IDEMPOTENCY_UNAVAILABLE.
- Envelope operation의 실패 해석에서 KEYED 명령이 그 답을 받으면
  AdmissionOutcome에 keyedResend를 싣는다. 재시도 루프는 그때 retryBudget·
  MAX_RETRY_ATTEMPTS·상한 2 안에서 같은 frozen 요청(같은 Idempotency-Key)을
  다시 보낸다. certainty는 MAYBE_APPLIED로 두어, 다 쓰면 결과 불명으로 끝나고
  키를 지킨다.

버린 대안
- V2처럼 KEYED의 모든 재시도 가능 status·network 실패에서 재시도: 정본 8.3이
  응답 없는 실패 뒤 재시도를 금지한다.
- 409 IDEMPOTENT_IN_FLIGHT도 자동 재시도: 처리 중 요청은 47fec5c의 사용자
  재전송(Retry-After 대기)이 이미 같은 키로 다룬다. V2도 409는 자동으로 다시
  보내지 않았다.

위험·한계
- retryBudget이 0인 명령(참조 기능 CREATE)은 그대로 다시 보내지 않는다.
- Envelope가 아닌 operation은 백엔드 code를 몰라 이 재전송이 없다.

검증
- RED: tests/integration/http-execution-v3-envelope.test.ts "KEYED resend on
  the backend's pre-execution refusal" 3건 중 2건 실패(한 번만 보내고
  PROBLEM). 다른 503(REQUEST_TIMEOUT)을 다시 보내지 않는 행은 처음부터 통과.
- GREEN: 같은 파일 35건 통과. 두 번 보낸 키가 같다.
- check:types, lint, check:architecture, test:unit 2,568, test:integration 117,
  test:component 245, tests/features 99 통과.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.7
2026-11-03 22:22:35 +09:00
DongHyeonka 365d8c3c02 fix(contracts): 쿠키 인증 쓰기는 CSRF 헤더를 요구하는 프로필만 조립한다
문제
브라우저는 쿠키를 어느 사이트의 요청에든 붙이므로, 쿠키로 인증하는 쓰기
요청은 페이지만 넣을 수 있는 헤더(CSRF 토큰)가 있어야 서버가 진짜 요청을
가른다. V2 클라이언트는 resolveRestSecurityProfiles로 "쿠키 프로필 + GET·HEAD
밖 method면 HEADER CSRF 프로필"을 강제했다. 048f490·12f3bb7이 V2를 지운 뒤
V3에는 이 검사가 없다. V3 프로필 설치 규칙은 SAME_ORIGIN_COOKIE에 쿠키
전송과 bearer 금지만 요구한다. 그래서 제품이 CSRF 헤더 없는 쿠키 프로필을
POST에 붙여도 조립이 통과한다.

고른 방법
assertHttpContract가 operation의 auth profile을 설치된 레지스트리에서 찾아,
쓰기(GET·HEAD 밖)인데 SAME_ORIGIN_COOKIE이고 requiredCredentialHeaders에
x-csrf-token·x-xsrf-token이 없으면 operation·method·프로필 이름을 담아
거절한다. 읽기 쿠키 프로필은 CSRF 없이 그대로 된다(tech-log·memento 예시와
같다).

버린 대안
- 프로필 설치 때 모든 쿠키 프로필에 CSRF 요구: 읽기 전용 쿠키 프로필
  (MEMENTO_BFF_READ 등)까지 막는다. method는 operation에만 있다.
- 요청 때(attachCredentials) 검사: 조립 때 잡을 수 있는 설정 실수를 사용자
  요청 시점까지 미룬다.

위험·한계
- 이미 CSRF 없는 쿠키 쓰기 프로필을 쓰는 제품은 조립이 실패한다. 의도한
  실패다(CHANGELOG [보안]).
- 헤더 값이 올바른 CSRF 토큰인지는 서버만 안다. 프론트는 헤더가 반드시
  실리는지만 보장한다(requiredCredentialHeaders가 없으면 fetch 0회).

검증
- RED: tests/unit/rest-profile-contract.test.ts "refuses a write whose cookie
  profile requires no CSRF header" 실패(조립이 통과).
- GREEN: 같은 파일 7건 통과. CSRF를 요구하는 쓰기와 CSRF 없는 쿠키 읽기는
  조립된다.
- check:types, lint, check:architecture, check:registries, test:unit 2,568,
  test:integration 117, test:component 245 통과.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.7
2026-11-03 22:22:35 +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 fbd93ac9a8 docs: 거절 적용 여부를 백엔드 기준 표로 바꾼 것을 매뉴얼과 기록에 적는다
문제
3261208이 V2·V3의 거절 판정을 계약 문서 6.1절 표로 바꿨다. 매뉴얼 02
4절은 아직 "422 전부와 필드 목록 400은 적용 안 됨, 그 밖은
classifyProblem"으로 적고, 리뷰 README 14.6 판정 표, 14.4의 검증 거절 줄,
CHANGELOG의 7db32e1 행도 같은 옛 규칙을 적는다.

고른 방법
- 매뉴얼 02 4절: 표의 세 code(적용 안 됨)와 그 밖의 400·409·422(결과 불명),
  근거가 계약 문서 6.1절이라는 것, 쓰기 전 거절 code를 새로 만들 때 두 곳을
  함께 고친다는 것.
- 매뉴얼 01 3단계: 실행기가 정하는 status 범위를 400·409·422와 503으로 적었다.
- 리뷰 README 14.6: 판정 표를 새 표로 바꾸고 처음 규칙을 한 줄로 남겼다.
  "6.1 표 반영" 단락에 바뀐 것, 버린 대안, 위험, RED·GREEN, 게이트를 적었다.
  14.4 줄에 바뀐 판정을 덧붙였다.
- CHANGELOG: [계약] 행 하나를 더하고 02e35d2·7db32e1 행이 그 행을 가리키게
  했다.

위험·한계
- 계약 문서 6.1절은 오케스트레이터 브랜치(ed0e4b1)에만 있다. 이 브랜치의
  매뉴얼은 그 절을 가리키지만, 합치기 전에는 그 절이 없다.
- 프론트 계약 문서 4.2절 "422 field validation" 행은 고치지 않았다.

검증
- verify:documentation PASS_SCOPED.
- tests/unit/changelog-review-ids.test.ts 통과.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.4, 14.6
2026-11-03 20:34:23 +09:00
DongHyeonka f3b87b3f02 docs: 생성한 기능이 짝 백엔드 Envelope를 읽는다는 결정과 결과를 적는다
문제
매뉴얼 01 3단계, CHANGELOG 미출시 절, 리뷰 README 14.3은 "생성한 기능은
짝 백엔드 응답을 그대로 읽지 못한다, 해결 방법은 정하지 않았다"를 알려진
제한으로 적는다. 7db32e1로 V3가 responseEnvelope: "ENVELOPE_V1"
operation의 Envelope를 읽게 되어 이 문장들이 틀렸다. 매뉴얼 02 4절의 503
흐름도와 계약 문서 4.1절도 "V3는 Envelope 없이 DTO를 검증"으로 적는다.

고른 방법
- 리뷰 README 14.6: 선택지 넷(V3 operation 단위 / provider 단위 / 백엔드
  problem+json 모드 / 기능 스키마가 감쌈)의 판정과 이유, V2와 같은 판정
  표, 의도한 차이 세 가지, RED→GREEN·게이트 결과, 남은 것. 14.3 행의
  처리 칸은 14.6을 가리킨다.
- 매뉴얼 01 3단계: "응답 모양"을 짝 백엔드 Envelope 기준으로 다시 쓰고,
  Envelope가 아닌 백엔드에 붙이는 순서(responseEnvelope 줄 삭제, problem
  details 스키마)를 따로 적었다. 알려진 제한 문단은 지웠다.
- 매뉴얼 02 4절: 실행기가 먼저 정하는 판정 목록과 바뀐 503 흐름.
- CHANGELOG: [계약] 행 하나, 알려진 제한을 남은 차이(참조 기능 미선언,
  V2와의 차이 셋, e2e 접근성 스펙의 [] 본문)로 바꿨다.
- 14.4와 CHANGELOG의 "V3 진단에 problem code가 없다"에 bd83b49가 싣는
  범위(멱등성 거절 reason 두 값)와 싣지 않는 것, 그 이유를 적었다.
- 계약 문서 4.1절·compatibility.md: Envelope를 읽는 곳을
  backend-envelope.ts로 고쳤다.

버린 대안
- 백엔드에 요청 문서 쓰기: (나)를 고르지 않아 요청할 것이 없다.

위험·한계
- 문서의 게이트 결과는 이 커밋 직전 트리(bd83b49, scaffold·sample-removal은
  7db32e1)에서 잰 값이다.
- 백엔드 링크는 두 repo가 나란히 있을 때만 열린다(기존과 같다).

검증
- verify:documentation PASS_SCOPED.
- 게이트 수치는 README 14.6 결과 표에 실행한 커밋과 함께 적었다.
- tests/unit/changelog-review-ids.test.ts 통과.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.3, 14.6
2026-11-03 20:13:31 +09:00
DongHyeonka 5c2f8b875c docs(manual): 매뉴얼만으로 기능을 추가한 실험의 막힘 5건을 메운다 (1101/16-01)
문제: docs/manual(7c7ef32)만 보고 notice-feature(목록·상세·작성, GET 2 +
KEYED POST 1)를 만든 실험(b58d131, 합치지 않음)에서 매뉴얼이 답하지 않아
코드를 읽어야 했던 곳이 나왔다.

| 막힘 | 절 | 매뉴얼에 없던 것 |
|---|---|---|
| 1 | 01-3단계 | 백엔드 Envelope와 뼈대 problem details 중 무엇을 따르나 |
| 2 | 01-3단계 | V2 입력 칸(requestSource, pathSchema, pathParameterNames, maxEncodedSearchBytes, boundary) |
| 3 | 01-5단계 | routeId가 무엇에 쓰이고 쓰기에는 어느 route를 적나 |
| 4 | 01-6단계 | 상세 경로를 items/ 아래 두는 이유, a11y spec 치환 고치는 법 |
| 5 | 01-10단계 | 같은 멱등 키 재전송과 요청 본문을 테스트에서 보는 법 |
| 덧 | 02-4절, 01-2단계, patterns | 503 IDEMPOTENCY_UNAVAILABLE 판정, 길이 제한 위치, 검색 폼 예 |

고친 절과 근거(코드 위치):
- 01-3단계 "응답 모양": 뼈대·MSW·V3 실행기는 DTO와 problem details를 쓴다.
  V3는 본문을 벗기지 않고 검증한다(src/adapters/http/http-execution-v3.ts:1410,
  1633-1647; src/adapters/http/index.ts:41-48; backend-api-and-server-state-
  contract.md:161-173). MSW는 {data} 감싼 응답을 실패 시나리오로 둔다
  (tests/mocks/handlers/http-scenarios.ts:80-81, 143-150). 뼈대 problem 스키마는
  최상위 code다(scripts/create-feature.ts:542-550). 짝 백엔드는 모든 JSON을
  Envelope로 보낸다(backend docs/web/http-contract.md:16-33).
- 01-3단계 "V2 행의 입력 칸": 칸 표와 공지 예 두 행. 근거
  src/contracts/api-operations.ts:9,25-27,112-125,142-190,
  src/contracts/schema-registry.ts:6-11, config/contracts/registry-governance.json:220
  (boundary는 허용값만 검사), tests/unit/http-operation-v2-v3-parity.test.ts:39-49,91,
  src/adapters/http/request-builder.ts:129-135(V2만 읽음),
  src/contracts/external-contract-runtime.ts:33,
  src/adapters/http/http-contract-bridge.ts:225-231(V3 고정 상한 8,192).
- 01-5단계 routeId: 실행기에 넘겨 관측 기록의 route_id로만 쓴다
  (src/adapters/http/feature-http-binding.ts:272-273,
  src/adapters/http/http-execution-v3.ts:248-254,653-655,
  src/bootstrap/runtime-adapters.ts:249-293). 기준은 "요청을 보내는 화면".
  참조 기능 생성은 LIST를 적었다(reference-http-gateway.ts:32-34).
- 01-6단계: items/ 이유(reference-feature-contract.ts:36-37, React Router
  정적 우선), a11y spec 치환 줄(tests/e2e/accessibility.spec.ts:26-29,36-43),
  파라미터 해석 실패 시 잘못된 경로 화면(src/presentation/routes/app-router.tsx:371).
  드릴 잔여물 검사는 기능 ID·폴더 이름만 찾는다(scripts/test-sample-removal.ts:
  114-117,383-392). URL 함수가 codec을 넘겨야 한다는 줄도 더했다
  (src/presentation/routes/route-codecs.ts:36,69-87; 생성 판
  scripts/create-feature.ts:934-938은 넘기지 않음).
- 03 "기능을 지울 때"·C절, 01-11단계: a11y spec 치환 줄을 손으로 지운다.
- 01-10단계, patterns "테스트": msw request:start로 요청을 모으는 예
  (실험 tests/features/notice-feature/notice-pages.test.tsx, msw 2.15
  node_modules/msw/lib/core/experimental/frames/http-frame.d.ts:58,
  생성 판 setupServer scripts/create-feature.ts:1147-1149).
- 02-4절 503: V3는 problem 스키마 실패면 쓰기를 MAYBE_APPLIED로 두고
  (http-execution-v3.ts:1633-1647), 통과하면 기능 classifyProblem이 정한다
  (src/adapters/http/http-effect-certainty.ts:99-131; 참조 기능
  reference-feature-contract-contribution.ts:49-70은 503을 MAYBE_APPLIED).
  V2 IDEMPOTENCY_REFUSALS에 503이 없어 effect가 비고
  (src/adapters/http/client.ts:1035-1038,1109-1135) 조정자가 MAYBE_APPLIED로
  본다(src/presentation/adapters/query/application-query.ts:824-834). 재전송은
  같은 키, 새 저장은 새 키(같은 파일 583-589, 636-669). 판정: 백엔드 행동
  (http-contract.md:94 "같은 키로 나중에 다시")과 맞는다. 화면 문구만 다르다.
- 01-2단계: 길이 제한은 경계 검증. 참조 기능도 스키마·폼에만 둔다
  (reference-schemas.ts:66, reference-resource-form.ts:9).
- patterns "URL 검색값을 바꾸는 폼": 짧은 예(SearchField, CollectionPage
  toolbar, buildRouteUrl search).
- errors.md: V2 입력 칸 실패 메시지 3개와 Unregistered route codec.

남긴 것:
- 응답 모양 제한: 지금 생성한 기능은 짝 백엔드의 Envelope 응답을 읽지
  못한다. 매뉴얼에는 제한과 선택지 둘(백엔드가 DTO를 보냄 / 프론트 V3가
  Envelope를 벗김)만 적었다. 결정은 없다. CHANGELOG·리뷰 기록은 이 커밋
  범위 밖이다.
- 경로 파라미터와 본문을 함께 받는 operation(PUT 등)의 V2/V3 일치 규칙이
  없다는 사실만 적었다.
- 예시 코드는 실험 브랜치의 notice 기능에서 옮겼다. 이 저장소에서 다시
  돌려 보지 않았다(실험 커밋 기록상 기능 테스트 21개 통과).

검증:
- node scripts/generate-product-feature-index.ts &&
  node scripts/verify-documentation-readiness.ts: PASS_SCOPED,
  documentReferences의 docs/manual 8개 파일 missing 0
- node scripts/run-vitest.ts run tests/unit/deletable-history-documents.test.ts
  tests/unit/documentation-readiness.test.ts: 2 파일 16개 통과
- 새로 적은 실패 메시지·식별자: src·scripts·tests에서 모두 찾음.
  request:start는 msw 타입에서 확인
2026-11-03 08:01:49 +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