main(d1b9c087)에 하네스 PR #13이 들어가 루트에 `AGENTS.md`, `.claude/`,
`.gitattributes`가 생겼다. 이 브랜치는 그 셋을 루트 등록부에 optional로
미리 적어 두었다.
충돌 둘을 풀었다.
- `scripts/lib/removal-fixture.ts`: main은 문서 복사 목록에 `AGENTS.md`를
더했고 이 브랜치는 그 목록을 등록부의 `fixture-documents` 집합으로
바꿨다. 등록부의 `AGENTS.md` 항목에 그 집합을 적었다.
- `tests/unit/template-feature-removal-documents.test.ts`: main은 문서
목록에 `AGENTS.md`와 옛 a11y 기록 폴더를 더했다. a11y 기록은 이
브랜치에서 `docs/`로 옮겼으므로 `AGENTS.md`만 남겼다.
등록부의 `AGENTS.md`·`.claude`·`.gitattributes`는 이제 추적되는 항목이라
optional을 빼고 역할을 실제 내용으로 고쳤다. 추적되는 루트 항목과
등록부 항목이 서로 남는 것 없이 같다.
검증(desktop): 커밋별 5검사와 merge 게이트 14개, verify:documentation.
merge 단계(=PR)가 변경이 아니라 검사기 자신을 시험하는 명령까지 돈다.
검사기가 나쁜 입력을 거부하는지 보는 `*:fixture` 명령 15개, 모든 시험
파일과 검증 script가 게이트에 걸렸는지 보는 ungated 검사, CI 계약의
개수·해시 기준선(`config/ci/contract-baseline.json`)이다. 기준선은 게이트
명령 하나를 더하거나 빼도 OWNER·REASON을 붙여 다시 받아야 했다.
소유자 결정(2026-09-16)은 개수·배선 검사를 main 단계에 두는 것이다.
고른 방법(design-docs repo-structure/03-ci.md 7.3절 F2, README.md 3.3절,
소유자 승인 2026-11-07):
- 새 게이트 FE-GATE-029 `checker-self-tests`, 새 단계 `main`
(`MAIN_READY`, 승격을 막지 않는다), 새 job `main_gate`. 브랜치 push와
`workflow_dispatch`(stage=main)에서만 돈다. PR과 태그에서는 돌지 않는다.
- FE-GATE-001·005·008·010·013의 `*:fixture` 명령 15개와 그 증거
산출물 10개를 FE-GATE-029로 옮긴다.
- `check:ci`의 ungated 검사를 `scripts/check-ci-gating.ts`
(`check:ci:gating`)로 떼어 FE-GATE-029에 둔다. `check:ci`는 계약·
workflow 검사만 PR에서 돈다.
- 기준선 파일, `update:ci-contract-baseline`, 그 검사를 지운다(소유자
결정). 계약 모양은 ci-gates.ts의 의미 검사가 지킨다. 개수를 고정하던
단위 시험의 개수 단언도 뺐다.
남긴 것: 음성 타입 fixture(`check:types:fixtures`, FE-GATE-003)는
이름이 `*:fixture`여도 merge에 둔다. 검사기가 아니라 src의 포트·계약
타입을 시험한다. `TelemetryPort.emit`을 넓히는 변경을 PR에서 막는다(정리
3단계 9.3절 변이로 확인). merge 단계 명령 참조 64 → 49.
위험: 검사기를 망가뜨린 PR은 merge를 통과하고 main에서 빨개진다. 그
대가로 PR이 검사기 자기 시험을 기다리지 않는다(설계 7.5절의 같은 교환).
FE-GATE-029의 명령이 앞 게이트 산출물 없이 새 checkout에서 도는지는
desktop에서 따로 확인했다(PR 본문).
검증(desktop): check:ci, check:ci:gating, check:types, CI 시험 통과.
merge 단계·FE-GATE-029 실행 결과는 PR 본문에 적는다.
Refs: design-docs repo-structure/03-ci.md 7.3·7.4절, README.md 3.3절
merge 단계가 게이트마다 job 하나(행렬 14개)라서 PR마다 checkout,
setup-node, `pnpm install`을 14번 하고 브라우저 설치를 2번 한다. Gitea
runner는 소유자 기계 한 대다. 사례(Vite 등)는 설치를 job당 한 번으로
묶는다(design-docs repo-structure/03-ci.md 3.5절).
고른 방법(03-ci.md 7.3절 F1, 소유자 승인 2026-11-07):
- job 종류 `gate-sequence`를 더한다. job 하나가 게이트 여럿을 차례로
돈다. 게이트마다 `FE-GATE-NNN / <이름>` 단계이고 `if: !cancelled()`라
앞 게이트가 실패해도 다음 게이트가 돈다(행렬의 fail-fast: false와 같다).
- merge job 셋: `merge_static`(001·002·003·010·011·012, 소스를 읽고
빌드하는 검사), `merge_test`(004·005·006·007·013·020, 시험),
`merge_browser`(008·009, 브라우저 설치). release 단계는 셋을 모두
기다린다. 게이트 id·명령·증거·승격 공식은 그대로다.
- 증거 업로드는 job마다 하나(`merge-static-<run>` 등)다.
버린 것: 행렬을 두고 `pnpm install`만 캐시하는 방법. runner 한 대에서는
job 수만큼 checkout과 준비가 남는다. 게이트를 job 하나에 모두 넣는
방법은 브라우저 설치를 모든 게이트가 기다린다.
위험: 한 job 안의 게이트가 같은 작업 공간을 쓴다. 앞 게이트의 산출물이
뒤 게이트에 남는다. desktop의 merge 단계 실행(게이트를 한 checkout에서
차례로 도는 것)과 같은 조건이라 그 결과로 확인했다. 실제 Gitea runner의
`!cancelled()` 해석은 Actions를 켠 뒤 확인한다.
검증(desktop): check:ci, check:types, CI 시험 4파일 통과. 합치기
전후 merge 단계 게이트별 결과 비교는 PR 본문에 적는다.
Refs: design-docs repo-structure/03-ci.md 3.5·7.3·7.4절, README.md 3.3절
template-contract-documents.test.ts가 README 표를 찾으려고
docs/superpowers 경로를 문자열로 적었다. deletable-history-documents.
test.ts는 코드·테스트가 지워도 되는 문서를 가리키면 실패하므로,
desktop merge 단계의 FE-GATE-005에서 이 두 줄로 실패했다.
경로를 조각으로 이어 만든다(그 시험 자신과 같은 방법). 시험이 보는
것은 그대로다.
검증: desktop FE-GATE-005(트리 ada4015c)의 실패 줄이 이 파일 15·35줄
이었다. 고친 뒤 결과는 PR 전 merge 단계에서 본다.
소유자가 2026-11-07에 지적한 것(매뉴얼이 생긴 뒤에도 남은 샘플, 역할이
겹치는 루트 폴더, 0파일 검사, 문서 속 인프라 설정)은 매뉴얼과 리뷰가
먼저 잡아야 했다. 지금은 그 규칙이 글로도 검사로도 없다. 그래서 같은
지적이 다시 나와도 게이트가 모른다.
고른 방법(design-docs repo-structure/04-frontend-layout.md 11절, 기계
검사가 「예」인 규칙을 표의 게이트 칸대로):
- R4·R5 `tests/unit/example-feature-rules.test.ts`(FE-GATE-005): 샘플
목록은 FE-GATE-020의 `test:sample-removal`(인자 없이, 빌드와 test:all
포함)이 증명한다. 목록 샘플의 기능 ID·라우트가 visual·e2e의 `goto`,
gates.json 산출물 경로, `config/scale/`에 나오면 실패한다. 템플릿
목록은 비어 있어 가짜 샘플로 판정 함수를 시험한다.
- R6·R7(문서) `verify:documentation`(FE-GATE-017): `docs/manual/`이 목록
샘플 경로를 가리키면, 현재 문서에 ```nginx```·```hcl``` 블록이나
`kind: Deployment` 같은 매니페스트 줄이 있으면 실패한다. 이력 폴더는
보지 않는다. 산출물 `documentation-review.json`에
`layoutRuleViolations`를 더했다.
- R7(파일)·R9 `tests/unit/repository-layout.test.ts`(FE-GATE-005):
nginx·Terraform·Helm·Kustomize 파일과 Kubernetes 매니페스트 YAML이
추적되면 실패. 옵션이 같은 tsconfig 쌍이 있으면 실패.
- R3은 `tests/unit/tracked-artifacts.test.ts`, R8은 앞 커밋의
`check-typecheck-inputs.ts`·`check-type-fixtures.ts`가 맡는다. R10의
기계 몫(루트 *.md 등록)은 R1이다.
- 매뉴얼 03에 E절(R1~R10 규칙과 검사, 루트 항목을 더하는 순서)과 C절
「Web Worker를 들일 때 tsconfig 더하기」(결정 D4)를 더했다.
위험: R5는 문자열 검색이라 샘플 ID를 다르게 쓴 대상(예: 라우트 경로를
조립하는 spec)은 놓친다. R7 문서 검사는 코드 블록 언어 태그와 매니페스트
줄로만 본다. R13(리뷰 가이드)은 design-docs 몫이라 넣지 않았다.
검증(desktop): 이 커밋에서 test:unit, check:types, check:ci, lint,
verify:documentation, check:architecture를 돌렸다.
Refs: design-docs repo-structure/04-frontend-layout.md 11절, README.md 3.4절
루트 항목 하나를 옮기려면 코드 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절
음성 타입 fixture마다 옵션이 같은 tsconfig 하나, package script 하나,
게이트 명령 하나가 있었다(23벌). 옵션은 모두 같고 파일 하나만 달라서
fixture를 더할 때마다 세 곳을 같이 고쳤다. `tsconfig.recipes.json`도
`tsconfig.test.json`과 lib가 같고 types만 하나 적었다.
`tsconfig.web-worker.json`은 `files: []`로 0파일을 검사하고 통과했다
(2026-09-25 리뷰가 기록, FE-GATE-003이 통과로 보였다).
고른 방법(design-docs repo-structure/04-frontend-layout.md 5.3절 (가),
소유자 승인 2026-11-07):
- fixture 첫 줄에 기대(`// expect: TS2322`, `// expect: pass`)를 쓰고
`scripts/check-type-fixtures.ts`가 fixture마다 `.tmp/type-fixtures/`에
한 파일 tsconfig를 써서 tsc를 돈다. 판정은 run-ci-gate.ts가 명령마다
하던 것과 같다(exit 1과 `error TS<code>:`). 결과를 fixture별로 출력한다.
기대 줄이 없는 fixture와 fixture 0개는 실패한다.
- recipes는 `tsconfig.test.json` include로 옮긴다.
- web-worker tsconfig와 script는 지운다(결정 D4). Worker를 들일 때 더하는
단계는 매뉴얼 03에 쓴다(뒤 커밋).
- `scripts/check-typecheck-inputs.ts`를 `check:types` 끝에 둔다. package
script가 tsc에 넘기는 tsconfig마다 이 repo 파일이 1개 이상인지 본다.
`files: []` tsconfig가 통과로 보이던 구멍을 막는다(R8).
버린 것: TypeScript API로 한 프로세스에서 돌리는 방법. 이 repo의
TypeScript 7.0(네이티브판)은 JS API를 싣지 않는다. 위반마다
`@ts-expect-error`를 쓰는 방법(5.3절 (나))은 오류 코드 고정을 잃는다.
위험: recipe가 이제 `vite/client` 타입이 있는 프로그램에서 검사된다.
recipe가 `import.meta.env`를 쓰면 전에는 실패했고 이제는 통과한다
(복사한 제품도 Vite라 가치가 작다, 설계 5.1절). CI 계약 기준선을 다시
받았다(명령 99 → 76).
검증(desktop): `check:types:fixtures` 23개 PASS, 각 fixture의 기대 코드가
출력에 그대로 나온다. `TelemetryPort.emit` 인자를 `string`으로 넓히는
변이(2026-09-25 리뷰 07-05)에서 `invalid-diagnostics-port.ts`가 TS2578로
FAIL, 실행기 rc=1. 되돌린 뒤 작업 트리 0줄. `check:types` rc=0
(Typecheck inputs: app 379, node 312, service-worker 22, test 915).
Refs: design-docs repo-structure/04-frontend-layout.md 5.3·9.2·9.3절, README.md 3.4절 D4
README의 지워도 되는 파일 표가 루트 CLAUDE.md를 "템플릿 repo 자신의
리뷰 지시, 자기 것으로 바꿔라"로 분류했다. 소유자 결정(2026-11-07 Q4)은
루트 지침을 템플릿 계약으로 정했다. 그리고 AGENTS.md와 docs/work/는
verify:documentation 범위 밖이라 그 안의 경로·script·게이트 ID가 틀려도
아무 검사도 알리지 않는다.
- README: 문서 절에 AGENTS.md와 docs/work/ 포인터를 더하고, 지워도 되는
표에서 CLAUDE.md 행을 빼고 docs/ledger/estimates.jsonl("줄을 비운다")을
넣는다.
- docs/README.md 1절: ../AGENTS.md, work/, work/reference/를 링크한다.
- tests/unit/template-contract-documents.test.ts: 지워도 되는 표에
AGENTS.md·CLAUDE.md·.claude·docs/work가 없고, 1절이 셋을 링크하는지
본다. 표는 제목이 아니라 docs/superpowers/ 행으로 찾아 제목을 옮겨도
돈다. 문서를 읽으니 REMOVAL_FIXTURE_DOCUMENT_TESTS에 올렸다.
- deletable-history-documents.test.ts: CLAUDE.md 패턴을 뺀다(이제 지워도
되는 문서가 아니다).
- 제거 드릴의 문서 사본(REMOVAL_FIXTURE_DOCUMENT_TARGETS)과
template-feature-removal-documents.test.ts의 사본에 AGENTS.md를 더한다.
사본 안에서 검사기를 돌리므로, 1절이 링크한 AGENTS.md가 없으면
FE-GATE-020과 그 단위 시험이 실패한다.
버린 대안: AGENTS.md를 링크하지 않고 백틱으로만 적기. 검사가 빠진다.
위험·한계: 문서 체계 세션이 README를 한국어로 옮기면 표 제목이 바뀐다.
새 시험은 행으로 찾지만, verify-documentation-readiness.ts의 지운 이력
목록은 영어 제목을 읽으니 그 세션이 같이 고친다.
검증: 새 시험은 README·docs/README.md를 고치기 전 트리에서 둘 다
실패했고(desktop test:unit), 고친 뒤 통과한다. verify:documentation과
merge 단계는 PR 전 합친 트리에서 돌린다.
Refs: design-docs harness/01-harness-design.md 4.4절·13절 Q4
샘플 라우트를 지워 라우트가 3개가 되자 FE-GATE-003의 route-runtime 음성 fixture가
TS2740 대신 TS2739를 내 기대 진단과 어긋났다. tsc는 빠진 키가 많으면 TS2740,
적으면 TS2739를 낸다. fixture가 정확히 한 라우트만 빼도록 바꿔 어느 라우트 수에서나
TS2741이 나오게 하고 기대 진단을 맞췄다.
config/scale/feature-shape-growth.json은 참조 기능 사본으로 잰 값이고,
기준 근거(feature-shape-ceilings.json의 axes)도 그 수치를 쓴다. 앞
커밋들이 측정 대상을 생성 기능으로 바꾸고 샘플을 지웠다.
샘플을 지운 트리(8c4b09b7, 수정 파일 없음)에서 node
scripts/scale/measure-feature-shape-growth.ts --sizes=0,25,100
--repeats=2 --write로 다시 쟀다. 기능당 tsc instantiation 약 10.1만,
tsc 메모리 약 31MB, 지연 JS 약 6.7KB와 9파일, 라우트 3개다. axes의
문장을 이 값과 firstFeatureGzipBytes에 맞췄다. 기준선 시험이 측정
대상(sourceFeature)도 본다.
위험: 시간 값은 desktop(i5-10400F, 부하 기록 포함)의 것이다. 400개 이상은
재지 않았다(D-18 선택).
검증(desktop): 같은 크기의 두 반복에서 컴파일러 수치가 같다.
tests/unit/feature-shape-growth.test.ts 통과.
소유자 결정(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.
규모 측정(S4 3.1절 S-6)은 참조 기능을 복사해 이름을 바꿔 잰다.
create:feature의 planFeature로 사본마다 --with-create --keyed 기능
파일을 만든다(자기 계약 패키지와 topic, context당 200개). 초기 JS
기록에 firstFeatureGzipBytes를 더하고, context 비용은 둘째 기능을 새
context에 둘 때와 같은 context에 둘 때의 차이로 잰다. 옛 정의는 기능이
없는 템플릿에서 첫 기능의 공용 코드까지 context 비용으로 세어 5,788B로
상한 512B를 넘었다. 몇 바이트짜리 비용에는 기록 허용치 하한 16B를
둔다(빌드 ID에 따라 gzip이 1~2B 흔들린다). 이 트리(샘플이 아직 있는
상태)의 기록: 204,266B, 27파일, 첫 기능 797B, 기능 521B, context 12B.
위험: 성장 기준선(0·25·100개)은 샘플을 지운 트리에서 뒤 커밋이 다시
잰다. 이 커밋의 기준선 파일은 아직 참조 사본으로 잰 값이다.
검증(desktop): feature-shape-growth 등 4파일 57 passed, test:unit 통과.
참조 기능 e2e 3개가 "기능 하나가 실제 브라우저에서 라우트·폼·
저장까지 된다"를 맡는다. 청크 복구, 부트 실패, preload 시험도 설치된
기능에 기댄다.
S4 9.1절 (가)대로 한다. scripts/lib/generated-feature.ts가 저장소
사본에 create:feature order-feature --with-create --keyed를 만들고,
spec은 그 사본의 빌드를 띄워 돈다. 참조 e2e의 검사(로그인, 목록, 폼
검증·이탈 확인·320px, en-US, 저장과 멱등 키, 429 뒤 다시 시도, 결과
불명과 같은 키 재전송, 키보드 포커스, 상태별 axe)를 생성 기능에
옮겼다. 오래된 탭의 청크 복구는 생성 기능 목록 라우트를, 부트 실패는
생성 기능을 넣은 사본을, preload 시험은 생성 기능 실행부 청크를 쓴다.
위험: 생성 기능의 동작만 본다. 제품 기능은 자기 spec이 필요하다.
사본 빌드가 spec과 브라우저마다 돈다(빌드 1초 안팎).
검증(desktop): 샘플을 지운 최종 트리에서 test:e2e 183 passed,
test:a11y 통과.
매뉴얼 예제 칸 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 통과.
src/features/local-draft-feature는 기능이 아니라 IndexedDB recipe의
소비자다. 시험 5개와 recipe가 쓰고, 그래서 생성기에 NOT_A_FEATURE
예외가 있었다(S4 3.1절 S-3).
코드를 tests/fixtures/indexeddb-consumer/로 옮기고 import만 고쳤다.
NOT_A_FEATURE 표식은 이 폴더만 썼고 다운스트림 둘에도 없어 생성기에서
지웠다. 선언 없는 폴더는 밖으로 옮기라는 메시지로 실패한다. 매뉴얼
오류표, README, starter-experience, capability-consumer-experience,
patterns를 고쳤다.
위험: fixture는 기능 폴더 밖이라 기능 계층 규칙(dependency-cruiser)이
걸리지 않는다. recipe가 tests/ 아래 파일을 type import한다.
검증(desktop): test:contract, test:recipes, test:browser-capabilities,
test:unit 통과.
셸 동작을 보는 e2e(반응형, 스크롤 복원, 해시 링크, 타이포그래피,
건너뛰기 링크, 메뉴 이동, 운영 CSP, compact, en-US의 lang)가 지울 예제
화면을 열거나 그 메뉴를 누른다.
홈과 /examples/platform으로 옮겼다. 스크롤 복원은 계약 표가 그려진 뒤
스크롤하고, 해시 링크는 비동기 표보다 위에 있는 첫 절을 대상으로
한다. WebKit은 scroll anchoring이 없어 표 아래 대상이 1px 밀렸다.
갤러리 자체의 320px 리플로는 앞 커밋의 workshop 시험이 맡는다.
위험: 홈과 플랫폼 개요의 모양이 바뀌면 이 시험들의 대상도 바뀐다.
검증(desktop): 샘플을 지운 최종 트리에서 test:e2e 183 passed.
예제 화면 /examples/ui·/examples/states가 visual 골든 2장과 갤러리
브라우저 시험의 대상이다. 2026-11-07 소유자 결정으로 예제 화면을
지우므로 그 역할을 먼저 옮긴다(design-docs repo-structure/
04-frontend-layout.md 9.2절 2단계 (1)).
두 갤러리 화면을 그대로 src/presentation/design-system/
galleries.stories.tsx로 옮겼다. 화면 단위 story(parameters.page)는
preview가 여백을 더하지 않아 앱 안과 같은 폭으로 그려진다. visual
설정은 Storybook 정적 빌드를 두 번째 web server로 띄우고
(TEST_VISUAL_WORKSHOP_PORT, 빌드 명령은 workshop 설정과 같은
scripts/lib/storybook-static.ts), 골든 2장은 그 story를 찍는다. 어두운
골든은 테마 선택기가 없어 시스템 dark(colorScheme)로 그린다. e2e의
갤러리 상호작용(텍스트 필드, 모달 포커스, 메뉴·탭·토스트, 열린 대화
상자 axe, 320px 리플로)은 tests/storybook/galleries.spec.ts로 옮겼다.
위험: 골든의 픽셀 색 허용치(threshold 0.2)는 그대로다. 미세한 토큰
변화는 옛 골든처럼 새 골든도 잡지 못한다.
검증(desktop): test:storybook 6 passed, test:visual 7 passed,
playwright-run-isolation 단위 시험 통과. 변이 확인: --color-action을
파랑→빨강으로 바꾸면 새 골든이 어두운 쪽 42,313px, 밝은 쪽 22,359px
차이로 실패했다. 옛 골든(main f33e4778)도 40,238px, 22,511px로 실패했다.
미세 변이(어두운 --color-danger red-500→600, 밝은 --color-danger-surface
색상각 25→145)는 옛·새 골든 모두 통과했다. 변이는 되돌렸다.
문제: 끝난 작업의 기록이 루트 폴더 둘에 따로 있다. tasks/는 2026-09-25
리뷰 수정 라운드(v0.2.0으로 끝남)의 계획·작업 목록·인계·레인 지시서와
레인 준비 스크립트 5개, .superpowers/는 2026-08-01 런타임 정합성 수정의
작업 보고 1개다. 읽는 코드는 없다(tests/unit/deletable-history-
documents.test.ts가 지킨다). 소유자가 2026-11-07 백엔드와 같이 이력
폴더로 옮기기로 정했다.
고른 방법:
- tasks/ → docs/history/plans/2026-09-25-review-fix-round/ (lanes/ 유지),
.superpowers/sdd/2026-08-01-runtime-correctness-remediation/
task-5-report.md → docs/history/evidence/2026-08-01-runtime-correctness-
remediation/. 폴더 이름은 docs-system 2절과 백엔드를 따른다.
- .md 5개 맨 위에 docs-system 4.1절 머리 블록 9줄(빈 줄 포함, 백엔드와
같은 모양)을 단다. 본문은 바꾸지 않았다: 블록 9줄을 빼면 옛 파일과
바이트가 같다(cmp). setup-lane.sh는 실행 파일(첫 줄 shebang)이라 블록을
달지 않고 그대로 옮긴다(R100). 같은 폴더 LANE-BRIEF.md의 블록이 그
파일을 설명한다.
- 상태: 계획서 넷은 끝남. 기계 규칙(체크 상자가 모두 표시돼야 끝남)으로는
plan·todo가 확인 안 함이지만, 이력이 라운드의 끝을 정한다(CHANGELOG
0.2.0, 태그 v0.2.0 2026-09-27). 증거는 보관.
- 작성일: plan·todo는 2026-09-25. git이 처음 더한 날(ea0f01f,
2026-09-24)은 이 파일이 앞 라운드(src 리뷰) 계획이던 때이고, 지금
본문은 c5f379b(2026-09-25)가 통째로 다시 썼다. handoff는 본문 날짜 줄
(2026-09-26 01:10), LANE-BRIEF는 git이 처음 더한 날(54ba358,
2026-09-26), 보고는 git이 처음 더한 날(d9afccd, 2026-08-02).
- docs/README.md: 3절 지도에 history/ 행을 더하고 옛 경로 → 새 경로를
적는다. 블록 첫 줄이 가리키는 「기록 문서의 머리 블록」 절(4절)을
더한다. ../tasks/ 링크는 없앴다. README.md의 "Files you can delete
after copying" 행도 docs/history/로 바꾼다.
- deletable-history-documents.test.ts: docs/history 패턴을 더하고
tasks/ 패턴은 뺀다. 루트 tasks/가 없어져 그 패턴이 지킬 문서가 없고,
남기면 제품의 "tasks/..." 라우트·폴더 문자열을 잘못 잡는다.
버린 대안: 옮긴 파일을 가리키는 다른 기록(docs/superpowers/plans/
2026-08-02-*.md, docs/reviews/2026-09-25-maturity-review/, SPEC.md)의
옛 경로를 고치기. 기록 본문은 고치지 않는다(docs-system 1절). 대신 지도
행에 옛 경로를 적었다.
위험·한계: SPEC.md는 이번에 옮기지 않는다. 27~37줄 「공통 완료 기준」을
작업 매뉴얼(docs/work/improve.md, 뒤 단계)로 옮긴 뒤 같은 폴더로 보낸다.
secret-scan-policy.json의 trackedRoots와 루트 경로 목록 7곳에는 tasks,
.superpowers가 없어 바꿀 것이 없다.
검증:
- 옮긴 .md 5개: 첫 9줄을 빼면 옛 파일과 cmp가 같다. git diff -M이
R091~R100 rename으로 잡고 지운 줄은 0이다.
- desktop(네 커밋의 끝 30a379f, 로그 ~/l1-layout-cleanup-logs/):
deletable-history-documents.test.ts는 지금 트리에서 통과하고, 테스트
폴더에 "docs/history/plans"를 담은 파일 하나를 두면 그 줄을 내며
실패한다. verify:documentation: PASS_SCOPED. test:unit 3091 tests 통과.
Refs: design-docs repo-structure/04-frontend-layout.md 2.1절, 9.2절;
design-docs conventions/docs-system.md 2·4절
문제: .gitignore가 artifacts/를 확장자별로만 무시한다(*.json, *.xml,
*.txt, *.sarif, *.log). 규칙에 없는 확장자가 새어 들어와 화면 캡처 3개
(artifacts/local-preview/*.png)와 커버리지 보고서 10개
(artifacts/tests/coverage-gateway/)가 추적된다. 읽는 코드·게이트·문서는
없다(git grep 'local-preview', 'coverage-gateway' 0건, 리뷰 기록 제외).
0929/14-01이 찾았고 2026-11-06 리뷰까지 '일부'로 남았다.
고른 방법:
- 13개를 지운다.
- artifacts/를 폴더째 무시하고 .gitkeep 2개와 수동 a11y 기록
(artifacts/tests/a11y-manual/*.md)만 다시 넣는다. git은 무시한 폴더
아래 파일을 다시 넣지 못해서, 지나가는 폴더마다 다시 넣고 그 내용을
다시 무시한다. 확장자·폴더별 옛 규칙은 모두 이 안에 들어가 지웠다.
- tests/unit/tracked-artifacts.test.ts가 git ls-files artifacts를 허용
목록과 대조한다. git add -f로 넣은 파일도 잡는다.
버린 대안:
- artifacts/** 와 !artifacts/**/ 꼴: git에서는 같게 되지만
verify:documentation이 .gitignore를 읽는 방식
(scripts/verify-documentation-readiness.ts generated())이
!artifacts/**/ 를 "artifacts 아래 전부 다시 넣음"으로 읽는다. 그러면
문서가 이름 부르는 생성 산출물(artifacts/quality/... 등)이 없는 경로로
실패한다(코드 읽기로 확인).
- 확장자 규칙에 *.png, *.html, *.info를 더하기: 다음 새 확장자에서 같은
일이 난다.
위험·한계: a11y 기록 말고 사람이 쓴 파일을 artifacts/에 두면 이제
무시된다. 지금 추적 파일 12개는 모두 허용 목록 안이다. 다운스트림은 지운
13개를 고치지 않았으면 병합이 그대로 지운다.
검증(desktop, 네 커밋의 끝 30a379f에서 한 번. 커밋마다 따로 돌리지는
않았다. 로그 ~/l1-layout-cleanup-logs/):
- tracked-artifacts.test.ts: 지금 트리 통과. 지운 png 3개를 index에
되돌리면 실패하고 그 3개를 낸다. 허용 목록 밖 note.txt를 git add -f
하면 실패하고 그 파일을 낸다.
- 새 .gitignore를 빈 저장소에 두고 산출물 15개를 만든 뒤 git add -A:
.gitkeep 2개와 a11y .md 1개만 추적된다(노트북).
- git ls-files artifacts: 12개(.gitkeep 2, a11y-manual/*.md 10).
- corepack pnpm test:unit: 212 files, 3091 tests 통과.
verify:documentation: PASS_SCOPED. check:architecture, check:types,
lint, check:ci, check:adapter-inventory: exit 0.
Refs: design-docs repo-structure/04-frontend-layout.md 9.2절 1단계
문제: 80e7f1d의 isRefusedOnEveryAttempt는 kind가 VALIDATION_REJECTED면 code를
보지 않고 참을 돌려준다. 그 kind는 기능의 mapProblem이 정한다. 생성기는
선언한 <FEATURE>_INVALID를 VALIDATION_REJECTED로 옮기고
(scripts/create-feature-write-slice.ts mapProblem), 참조 기능 gateway는 code와
상관없이 모든 422를 그렇게 옮긴다(reference-http-gateway.ts). 그래서 기능이
선언한 code나 422 IDEMPOTENT_REQUEST_MISMATCH로 끝난 같은 키 재전송이 결과
불명을 푼다. 함수 주석, CHANGELOG, 런북 6.3-4는 이것들이 결과 불명으로
남는다고 적는다. 기존 테스트는 mapProblem 없이 실패를 만들어 이 길을 타지
않았다(최종 리뷰 FR-01).
고른 방법(메인 세션 결정 "D10 보완 2"): 재전송 거절은 짝 백엔드 표의 code일
때만 결과 불명을 푼다. 지금은 400 VALIDATION_FAILED와 400
IDEMPOTENCY_KEY_INVALID다(REFUSALS_OF_EVERY_ATTEMPT, code와 status 함께). kind
줄을 지우고 kind로 입력 검증을 말하던 주석과 런북 6.3-4를 고쳤다. 기능 code는
상태 규칙일 수 있어 mapProblem이 정한 kind를 믿지 않는다. 400
VALIDATION_FAILED는 필드 목록이 있든 없든 전처럼 푼다.
테스트: 훅의 결과 불명 유지 it.each에 mapProblem 모양(VALIDATION_REJECTED +
선언 code, VALIDATION_REJECTED + 422 IDEMPOTENT_REQUEST_MISMATCH) 두 행을 더했다.
참조 페이지에서 422 재전송이 필드 오류와 다시 저장을 보인다던 테스트를, 결과
불명이 남고 확인이 보이는 테스트로 바꿨다. 리뷰가 요청한 대로 다시 마운트한 폼이
다른 값을 보이는 채 재전송해 422 IDEMPOTENT_REQUEST_MISMATCH를 받으면 결과
불명과 확인 버튼이 남는 테스트를 더했다.
버린 대안: kind 줄을 남기고 기능 선언 code만 빼기(실행기는 code가 선언인지
폼과 훅에 알리지 않는다).
위험·한계: 참조 기능처럼 problem details를 읽는 기능의 422 입력 검증은 재전송
뒤 결과 불명으로 남는다. 출구는 결과 불명 화면의 확인이다. 리뷰 실험 03-R1
X1~X3·X5는 그대로 키가 모두 key-1이어야 한다. CHANGELOG는 다음 커밋이 적는다.
검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/component/application-mutation-admission.test.tsx
tests/features/reference-feature/reference-page.test.tsx
tests/component/form-foundation.test.tsx tests/unit/backend-envelope.test.ts,
리뷰 실험 03-R1 패치를 이 커밋에 적용
Refs: 1106/03-01 (final review FR-01)
문제: 1106/08-01(fbaaaee)은 제출한 값이 없는(저장 중에 떠났다 다시 마운트한)
폼에서 settleApplied가 화면의 지금 값으로 성공을 정한다. 그 값은 보낸 적이
없다. 사용자가 결과 불명 동안 새 항목을 입력하고 앞의 저장을 "변경됨으로
확인"하면 "저장했습니다"와 함께 입력이 지워진다(기본 resetOnSuccess).
resetOnSuccess: false인 폼은 그 값이 기준값이 되어 dirty와 이탈 확인이 꺼진다
(diff 리뷰 DR-03).
고른 방법: 리뷰의 최소 방향대로, 제출한 값이 없으면 결과(success)와 포커스
이동만 한다. 값·기준값·touched는 건드리지 않고, 오류 표시만 비운다. 08-01의
완료 기준(확인 뒤 "저장했습니다."가 보이고 포커스가 feedback 안)은 그대로다.
버린 대안: 지금 값이 기본값과 같을 때만 정리하기(같은 결과에 분기가 하나 더
는다).
위험·한계: 다시 마운트한 폼에서 확인한 뒤 입력이 남아 있으면 dirty가 남아,
생성 기능 작성 페이지의 확인 뒤 목록 이동이 이탈 확인 창을 띄운다. 보내지
않은 입력을 지키는 쪽이다. CHANGELOG는 다음 커밋이 적는다.
검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/features/reference-feature/reference-page.test.tsx
tests/component/form-foundation.test.tsx
Refs: 1106/08-01 (diff review DR-03)
문제: 1106/03-01(2568587)은 결과 불명 요청을 같은 키로 다시 보낸 시도가
NOT_APPLIED·NOT_STARTED로 끝나면 이유와 상관없이 결과 불명과 키를 남긴다.
같은 요청이 매번 받는 거절(400 VALIDATION_FAILED, 400 IDEMPOTENCY_KEY_INVALID,
필드 목록이 있는 입력 검증)도 같다. 폼은 필드 오류를 버리고 "잠시 뒤 같은
요청으로 다시 보내 주세요"만 보인다. 저장은 꺼져 있고 다시 보내면 같은 400이
온다. 출구는 사실이 아닌 "변경됨으로 확인"이나 새로고침뿐이다. 815ea58
(1106/03-03)이 같은 길을 IDEMPOTENT 쓰기로 넓혔다(diff 리뷰 DR-01).
고른 방법(메인 세션 결정, D10 보충): 같은 키 재전송은 그 결과가 첫 요청에
무슨 일이 있었는지 보여 줄 때만 결과 불명을 푼다.
- 성공·APPLIED_CONFIRMED: 저장된 답의 재생이다. 지금처럼 푼다.
- 같은 요청이라 첫 요청도 받았을 거절: 푼다. src/contracts/errors.ts에
isRefusedOnEveryAttempt를 두었다. effect NOT_APPLIED이고, kind
VALIDATION_REJECTED(필드 목록이 있는 입력 검증)이거나 code·status가
REFUSALS_OF_EVERY_ATTEMPT(400 VALIDATION_FAILED, 400 IDEMPOTENCY_KEY_INVALID)다.
- 그 밖(429, 401, 403, 503 RATE_LIMIT_*, 422 IDEMPOTENT_REQUEST_MISMATCH(키가
이미 서버에 닿아야 나온다), 기능이 선언한 code(바뀌는 상태의 규칙일 수
있다), IDEMPOTENT 쓰기의 404·412 같은 다른 code, NOT_STARTED): 지금처럼
결과 불명과 키를 남긴다. 어느 쪽인지 모르는 code는 남긴다.
훅(resendLeavesUnknown)과 폼(resendLeftUnknown)이 같은 함수를 부른다. 폼은 푼
경우 처음 저장과 같이 보인다(필드 오류, 다시 받는 저장, 고친 값은 새 키).
남긴 경우 결과 불명 화면(확인·다시 보내기)이 그대로라 폼이 영영 막히지
않는다. 표는 backend-envelope.ts REFUSED_BEFORE_WRITE의 부분집합이어야 하고,
표의 나머지 행은 다른 쪽으로 분류된다. backend-envelope 단위 테스트가 둘을
대조해, 표에 새 행이 생기면 이 분류를 정할 때까지 실패한다. presentation은
adapters를 import할 수 없어(.dependency-cruiser.json) 판정을 contracts에 둔다.
버린 대안: 일시 거절(NOT_STARTED, retryable, RATE_LIMITED, RATE_LIMIT_*)만
남기기(diff 리뷰 안). 401·403과 422 IDEMPOTENT_REQUEST_MISMATCH, 기능 선언
code를 풀어 버린다. AppFailure에 새 칸을 더해 실행기가 표시하기(계약 타입과
실행기·바인딩을 함께 바꾼다).
위험·한계: 기능이 선언한 결정적 거절(생성 기능의 400 <FEATURE>_INVALID)은
어느 쪽인지 알 수 없어 결과 불명으로 남는다. 출구는 결과 불명 화면의
확인이다. 필드 목록이 있는 NOT_APPLIED는 기능 선언 code여도 입력 검증으로
본다. 리뷰 실험 03-R1 X1~X3·X5(503·429·NOT_STARTED)는 그대로 키가 모두
key-1이어야 한다. 런북 6.3-4를 고쳤다. CHANGELOG는 다음 커밋이 적는다.
검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/component/application-mutation-admission.test.tsx
tests/component/form-foundation.test.tsx
tests/features/reference-feature/reference-page.test.tsx
tests/unit/backend-envelope.test.ts, 리뷰 실험 03-R1 패치를 이 커밋에 적용
Refs: 1106/03-01 (diff review DR-01)
문제: e7b1b01 뒤 정책 테스트는 HTTP 자리 스키마의 행이
unknownFieldPolicy를 빼면 실패하고, 적으면 탐침 결과와 비교한다. 탐침이
객체에 닿지 못하는 검증기(두 탐침을 모두 루트에서 거절: `responseBody:
"NONE"` 출력의 z.undefined(), 문자열·null 본문)는 결과가 UNREACHED다.
행 타입은 REJECT_UNKNOWN·STRIP_UNKNOWN만 받으므로, 그런 operation은 행을
어떻게 적어도 통과하지 못한다. 칸을 빼면 `row states no
unknownFieldPolicy`, STRIP_UNKNOWN을 적으면 `row STRIP_UNKNOWN, validator
UNREACHED`다. 템플릿에는 그런 operation이 없어 다운스트림에서 난다.
고른 방법: 리뷰의 가장 작은 방향. 탐침 결과가 UNREACHED인 자리는 정책
비교에서만 빼고, direction은 그대로 요구한다. 두 검사를 슬롯·행을 받는
함수(directionProblems, policyProblems)로 꺼내, 설치된 descriptor 검사와
가짜 스키마 검사가 같은 함수를 쓴다. 새 describe가 z.undefined() 같은
NoContent 검증기로 탐침이 UNREACHED인지, 행이 direction을 빼면 실패하는지,
정책을 빼거나 적어도 통과하는지 본다. 매뉴얼 01, errors.md, CHANGELOG
1106 절의 먼저 할 일 1과 07-02 행에 적었다.
검사를 느슨하게 한 것이 아닌 이유: 탐침은 객체가 없는 스키마의 모르는
필드 정책을 판정할 수 없다. 그 자리의 비교는 맞는 답이 없는 질문이었다.
e7b1b01 전에는 칸을 빼면 이 자리 전체를 건너뛰었다. 지금은 direction을
요구하므로 그때보다 넓다. 객체에 닿는 스키마의 정책 비교는 그대로다.
버린 대안: 행 타입에 객체가 아닌 본문용 값을 더한다. src/contracts의
SchemaDefinition 모양, 분류기, 기준선이 함께 바뀐다.
위험·한계: 행이 UNREACHED 스키마에 적은 정책 값은 아무도 검사하지 않는다.
루트에서 이슈 하나로 거절하는 union(zod `invalid_union`, 예:
strict 객체 | null)도 UNREACHED가 되어 정책 비교에서 빠진다(추론, 실행하지
않음). 고친 곳이 테스트 파일 자신이라 RED는 테스트 파일만으로
만들 수 없다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/schema-metadata-policy.test.ts
Refs: 1106/07-02 (diff review DR-04)
문제: af3344b가 더한 Playwright spec 본문 검색은 대소문자를 무시하고
`_`를 이름 경계로 봤다(`(?<![A-Za-z0-9-])…(?![A-Za-z0-9-])`, `i`).
create:feature는 한 단어 ID(`messages`, `reports`)를 받고 폴더 이름도
ID와 같다. 그래서 `messages` 기능을 지우면 템플릿 자신의
tests/e2e/accessibility.spec.ts(`KO_MESSAGES`)와 scrollbar-gutter
visual spec이 잔여로 잡혀 드릴이 실패한다. `status`·`reports`는 템플릿
spec 여러 개가 평범한 단어로 쓴다. errors.md는 목록에 템플릿 파일이
나오면 템플릿 결함이라 적으므로 제품은 고칠 곳이 없다.
고른 방법: 메인 세션 기준대로 적힌 그대로(대소문자 구분) 찾고, 경계는
식별자 문자 `[A-Za-z0-9_-]`다. 폴더 이름이 ID와 다르면 같은 규칙을 쓴다.
그런데 이 둘만으로는 `status`·`reports`가 0건이 되지 않는다. 템플릿
spec에 `status: 200`, `getByRole("status")`, 테스트 제목의 "reports"가
있다(git grep). `getByRole("status")`는 따옴표 안 한 단어라 따옴표나
문맥 규칙으로도 실제 참조와 구별되지 않는다. 그래서 `-`가 든 이름만 spec
본문에서 찾는다. 한 단어 ID·폴더 이름은 spec 본문 검색에서 빠진다.
검사를 좁히는 변경이지만 이 발견이 바로 그 거짓 양성이다. 거짓 양성은
제거를 막고 고칠 길이 없는 반면, 빠지는 쪽(한 단어 ID만 본문에 적은
spec)은 1106/16-01 전처럼 다음 CI의 브라우저 게이트가 잡는다.
테스트: 템플릿의 spec 파일 전부를 사본에 옮겨 `product-feature`,
`messages`, `status`, `reports`로 돌리면 잔여 0건이다. 적힌 그대로의
ID와 다른 폴더 이름(`invoice-docs`)은 잔여이고, `Invoice-Feature`와
`invoice-feature_v2`는 아니다. 매뉴얼 01 11단계, errors.md, CHANGELOG
1106 절의 16-01 행·확인 2·알려진 제한을 고쳤다.
버린 대안: 따옴표나 `/features/` 문맥만 센다. `getByRole("status")`가
남고, `test.describe("invoice-feature")` 같은 실제 잔여도 문맥에 따라
빠진다. 한 단어 ID를 막는 생성기 규칙은 이 수정 범위 밖이다.
위험·한계: `-`가 든 흔한 이름(예: `read-only`)을 ID로 쓰면 템플릿 spec이
그 이름을 쓸 때 다시 거짓 양성이 난다. 템플릿 spec 0건 테스트는 네
ID만 본다. src 쪽 부분 문자열 검색(1105/16-04)은 그대로다. CHANGELOG
행의 커밋 칸에는 이 커밋 해시를 아직 적지 않았다(같은 커밋에 자기 해시를
적을 수 없다).
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/feature-residue.test.ts
node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts
Refs: 1106/16-01 (diff review DR-02)
문제: :root의 scrollbar-gutter: stable(1105/15-05)은 일반 스크롤바를 쓰는
브라우저에서 문서가 스크롤되지 않아도 오른쪽 15 px를 비워 둔다. 그 자리에는
root의 배경색이 보인다. 고정 위치 상자와 top layer의 ::backdrop은 그 자리
앞에서 끝나서, drawer·modal을 열면 오른쪽 끝에 가림막이 덮지 않은 밝은
세로 띠가 남는다. compact 골든(390 px, drawer 열림)이 가림막이 375 px에서
끝나는 모습을 정답으로 고정했다. header 띠도 같은 자리 앞에서 끝난다.
고른 방법:
- modal이 열린 동안 root 배경색을 가림막을 페이지 바탕 위에 겹친 불투명한
색으로 바꾼다. primitives.css의 :root:has(.ui-dialog[open])이
background-color: var(--dialog-backdrop-on-surface)를 쓴다.
- 새 컴포넌트 토큰 셋(component.css). --dialog-backdrop-weight(55%)를
--dialog-backdrop(::backdrop이 칠하는 반투명 가림막, 값은 전과 같다)과
--dialog-backdrop-on-surface(color-mix in srgb로 페이지 바탕과 섞은 색)가
같이 읽는다. 브라우저는 반투명 색을 sRGB에서 겹치므로 두 색이 맞는다.
- body가 페이지 바탕(--color-surface)을 직접 칠한다. 그래서 root 배경은
스크롤바 자리(와 overscroll)에만 보이고, 열린 modal 아래 페이지가 두 번
어두워지지 않는다. modal이 없으면 둘이 같은 색이라 화면이 그대로다.
- 검사: tests/visual/scrollbar-gutter.visual.spec.ts. 시각 프로젝트에서
Chromium을 --hide-scrollbars 없이 띄우고, 스크롤되지 않는 /not-found
(390x844)에서 스크롤바 자리와 바로 옆 가림막의 평균 픽셀 색을 비교한다.
닫힘 → drawer 열림 → 다시 닫힘 세 번 본다. 실패 메시지에 root의 계산된
배경(색·이미지)과 열린 .ui-dialog 수를 적어, 규칙이 안 맞은 것과 맞았는데
그 자리에 안 그려진 것을 구분한다. 08-R2 probe의 잘못된 단언 둘을
고쳤다. 자리가 비어 있으면 clientWidth가 창 폭이라 자리 위치는 body의
오른쪽 끝으로 찾는다. 그 자리의 hit test는 늘 null이라 픽셀을 본다.
허용 차이 12는 drawer 그림자(70 px blur)가 옆 띠를 약 3단계 어둡게 하는
몫이다. 덮지 않은 띠는 약 120 차이 난다.
- header 띠는 받아들이고 design-system-platform.md 8.2에 적었다. header
색으로 칠하려면 root 배경이 셸의 header 높이·색을 알아야 하고, 셸이 없는
화면에서는 그 띠를 빼야 한다. 완료 기준은 가림막만 요구한다.
버린 대안:
- 첫 시도: :root:has(.ui-dialog:modal)에서 가림막 색 gradient 한 겹을 페이지
바탕 위에 얹었다. desktop batch에서 그 자리가 페이지 바탕색 그대로였다
(gutter rgb(248 250 252), 옆 가림막 rgb(122 128 136)). 그 실행만으로는
규칙이 안 맞았는지(:modal의 :has() 무효화), 이미지 층이 그 자리에 안
그려졌는지 가를 수 없다. 그래서 둘 다 피한다. 배경색 자체를 바꾸고,
showModal()이 세우는 [open] 속성으로 고른다. Dialog primitive는 브라우저에서
늘 showModal()로 열기 때문에 열린 .ui-dialog는 modal이다.
- ::backdrop에 음수 inset(right: -N px): 스크롤바 자리는 viewport의
padding box 밖이라 고정 위치 상자가 잘린다(스펙 기준, 화면 확인은 안 함).
- scrollbar-gutter를 거두기: 15-05의 첫 화면 shift를 다시 연다.
- modal이 열린 동안 root 배경만 바꾸고 body를 비워 두기: 페이지 전체가
가림막 아래에서 한 번 더 어두워진다.
위험·한계: :has()를 모르는 브라우저(Firefox 121 미만 등)는 이 규칙을 버리고
전처럼 띠가 남는다. 그 자리 색은 가림막의 blur(2px)를 따르지 않는 평평한
색이다. 오른쪽 drawer(placement="end")는 drawer와 창 끝 사이에 가림막 색 띠가
남는다(템플릿은 쓰지 않음, 미확인). RTL, Firefox, WebKit은 보지 않았다.
문서가 스크롤되면 그 자리의 스크롤바는 전처럼 가림막 밖이다.
--hide-scrollbars로 찍는 compact 골든은 전체 페이지(1377 px)를 찍으므로,
열린 modal 동안 어두워진 root 배경이 창 높이(844 px) 아래의 오른쪽 15 px
띠에도 보인다. 실제 브라우저에서 그 부분은 스크롤바 아래에 있다. compact
골든 1장은 desktop에서 다시 찍었다(test:visual:update). 바뀐 것은 x 375~390
띠가 높이 전체에서 가림막 색이 된 것뿐이다. 나머지 골든 4장은 바뀌지
않았다(body와 root가 같은 색). 레이아웃은 바꾸지 않았다.
검증: desktop batch에서 확인.
corepack pnpm test:visual tests/visual/scrollbar-gutter.visual.spec.ts
corepack pnpm test:visual:update 뒤 corepack pnpm test:visual
node scripts/r5-15-scrollbar.mjs 3 <out.json> (15-R3, 첫 화면 shift 0 유지)
Refs: 1106/08-03
문제: 계약 문서 6.1절은 §4의 503 RATE_LIMIT_UNAVAILABLE·RATE_LIMIT_INCOMPATIBLE에
"자동 재전송은 없다(KEYED도 같다)"고 적는다. 코드는 다르다. 표가 NOT_APPLIED로
정하면 retryHint는 503의 재시도 status 여부이고, 실행기는 NOT_APPLIED인
SAFE·IDEMPOTENT 요청을 retryBudget 안에서 다시 보낸다. 조립은 쓰기의
IDEMPOTENT와 retryBudget > 0을 받는다. CHANGELOG(1105/03-02 행)와 커밋 c6c37f3
본문은 코드와 같다. 그 경로를 보는 테스트가 없다.
고른 방법: 6.1절 문장을 "KEYED·NEVER는 자동 재전송이 없다. IDEMPOTENT 쓰기는
retryBudget 안에서 Retry-After(5초 이하) 뒤 다시 보낸다. status로 판단하므로
retryable: false인 RATE_LIMIT_INCOMPATIBLE도 다시 보낸다"로 고친다. 통합
테스트가 IDEMPOTENT PUT(retryBudget 1)의 503 두 code → 200을 fetch 2회, 키
없음, SUCCESS로 고정한다.
버린 대안: INCOMPATIBLE을 다시 보내지 않게 표에 "재시도 안 함"을 싣기(리뷰가
선택으로 둔 별도 동작 변경이다. 쓰기 전 거절이라 중복은 없다).
위험·한계: 동작은 바꾸지 않았다. INCOMPATIBLE은 같은 답을 한 번 더 받는다.
템플릿 안에는 IDEMPOTENT 쓰기가 없다. 이 테스트는 부모 커밋에서도 통과한다
(문서 결함이라 RED가 없다).
검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/integration/http-execution-v3-envelope.test.ts, corepack pnpm
verify:documentation
Refs: 1106/03-02
문제: 생성기 템플릿의 작성 폼은 저장을 기다린 뒤 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
문제: 1105/12-04 뒤 빌드는 `RUN_OUTPUT_ROOT` 아래에 쓰는데,
check:bundle의 두 단계(`generate-supply-chain.ts`, `check-bundle.ts`)는 이
변수를 읽지 않고 checkout의 `dist`와 `artifacts/`를 읽는다. 셸에 이 변수를
둔 채 빌드와 check:bundle을 돌리면 예산을 3,504 B 넘는 새 빌드 대신 이전
빌드를 재서 PASS한다(리뷰 12-R2). ci:gate의 신선도 검사도 bundle.json을
check:bundle이 다시 쓰므로 막지 못한다.
고른 방법: `scripts/lib/run-isolation.ts`에 `checkoutBuildReadFailure`를
두고, 두 스크립트가 무엇을 읽기 전에 부른다. 출력 루트가 `.`이 아니면 변수
값과 이유를 적고 exit 1로 멈춘다. `.`(Playwright 설정이 run ID 없이 web
server에 넘기는 값)과 빈 값은 그대로 돈다. 그래서
`RUN_OUTPUT_ROOT=.tmp/x corepack pnpm ci:gate -- FE-GATE-012`도 check-bundle
단계에서 변수 이름을 적고 실패한다.
버린 대안: ci:gate가 시작 전에 거절하기(리뷰 문서 (b)). 12-R2처럼
check:bundle을 직접 돌리는 경우를 막지 못한다. 두 스크립트가 같은 루트를
읽게 하기(c)는 supply-chain 산출물 전부와 CI upload 경로를 함께 옮겨야 한다.
위험·한계:
- FE-GATE-012는 빌드 단계를 끝까지 돈 뒤 check-bundle에서 실패한다. 빌드
시간만큼 늦게 알린다.
- 같은 모양일 수 있는 `check:app-build-input:bundle`,
`check:optional-recipes --require-dist`, release candidate 조립은 보지
않았다. FE-GATE-012에서는 check-bundle이 먼저 실패해 거기까지 가지 않는다.
- 디버깅으로 변수를 둔 사람은 check:bundle 전에 지워야 한다(문서에 적음).
- 이 노트북에서는 실행하지 못했다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/check-bundle-output.test.ts tests/unit/run-isolation.test.ts
리뷰 12-R2 명령(stale-bundle-rc=1, stderr에 RUN_OUTPUT_ROOT), check:types,
lint, verify:documentation, ci:gate FE-GATE-012
Refs: 1106/12-02
문제: 저장 중에 참조 작성 폼을 떠났다가 돌아오면(1105/08-04가 지원 경로로
다루는 길) 새 폼 인스턴스에는 제출한 값도 결과도 없다. (A) 그 저장이 결과
불명으로 끝나 "변경됨으로 확인"을 누르면 settleApplied가 제출한 값이 없어
아무것도 하지 않는다. 결과 문구가 없고 눌렀던 버튼이 빠져 포커스가 body로
간다. 같은 훅의 재전송(resendUnknown)은 다시 마운트를 이미 처리한다.
(B) 그 저장이 성공하거나 적용 안 됨으로 끝나면 진행 문구만 사라지고 아무것도
보이지 않는다. 사용자가 같은 항목을 다시 입력하면 새 생성이 나간다(리뷰
probe 08-R1).
고른 방법:
- (A) 리뷰의 최소 개선 (1): settleApplied가 제출한 값이 없으면 지금 값으로
성공을 정한다. 재전송과 같다. 포커스를 잃었으면 feedback 자리로 옮긴다.
1105/08-01의 포커스 복구는 직전 결과가 effect-unknown일 때만 걸려서
다시 마운트한 폼(직전 idle)에는 닿지 않는다.
- (B) 리뷰 (2)의 작은 쪽: 참조 폼이 "자기가 시작하지 않은 저장이 돌던 것"을
기억하고, 그 저장이 끝나면 feedback에 기존 링크 "목록을 새로 불러와
확인"을 둔다. 이 폼이 직접 저장하면 지운다. 새 문구는 없다.
버린 대안: 코디네이터가 마지막 시도의 결과를 채널에 남기고 폼이 그것을
보이기(정확하지만 코디네이터 계약이 넓어진다), useAppForm이 코디네이터
상태를 받아 결과를 하나로 내기(지난 라운드 3.5 (B), 설계 변경이다).
위험·한계: (B)는 결과를 말하지 않고 목록으로 안내만 한다. 생성기 템플릿의
작성 폼은 (A)에서 목록으로 옮기므로 해당 없고, (B) 안내는 넣지 않았다
(1106/08-02는 이동만 고친다). (A)는 resetOnSuccess면 다시 마운트한 뒤 입력한
값을 비운다. 재전송과 같은 동작이다. 브라우저 3엔진 e2e는 더하지 않았다.
검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/features/reference-feature/reference-page.test.tsx
tests/component/form-foundation.test.tsx
Refs: 1106/08-01
문제: poll `execute`가 받는 `input.operation`은 `BoundedPollOperation`
(`InstalledHttpContract<unknown, unknown, unknown>`)이다. 권하는 대로
`executor.execute(input.operation, x, …)`를 부르면 `Input`이 `unknown`이
되어 `x`는 아무 값이나 통과하고 `outcome.value`도 `unknown`이다. 입력이
틀리면 런타임 `CONTRACT_VIOLATION`(INPUT_INVALID)으로만 드러난다. 타입을
지키려면 클로저 descriptor를 써야 해서 1103/04-01의 잔여 위험(다른 행을
실행) 쪽이 유리해진다. 또 V3 결과 9종을 poll 결과로 바꾸는 대응표가 없다.
repo의 유일한 V3 조합 예(테스트)는 SUCCESS 외 전부를 retryable
PROVIDER_UNAVAILABLE로 바꿔, 옮기면 401·403·입력 거절도 maxAttempts번
다시 요청된다.
고른 방법: 리뷰 선택지 (b) + (c).
- `createBoundedPollCoordinator`와 `BoundedPollCoordinatorDependencies`에
`Operation extends BoundedPollOperation = BoundedPollOperation`을 더하고
`operation`·`input.operation`을 `Operation`으로 둔다. `operation`에서
추론되므로 실행기 호출이 기능 descriptor의 입력·출력 타입으로 검사된다.
런타임 코드는 바뀌지 않는다.
- 설계 9.2에 V3 결과 kind마다 poll 결과(kind, retryable, retryAfterMs)를
적은 표를 두고, 13.1 PROVIDER_UNAVAILABLE 행에서 그 표를 가리킨다.
9.2 "auth에서 lease 종료", 9.3 "401은 attempt를 끝낸다", 9.4, 13.1과
맞췄다. `retryAfterMs`는 값이 있을 때만 둔다(빈 칸은 모양 오류).
- 테스트 조합 예를 표대로 바꿨다(`pollAttemptResult`). 503 재시도
테스트는 같은 결과다(503 PROBLEM → retryable PROVIDER_UNAVAILABLE).
- 테스트: 틀린 입력에 `@ts-expect-error`, 출력을 기능 타입으로 받는 타입
테스트 1건. 401·403이 요청 1번으로 lease를 끝내는 테스트 2건.
버린 대안:
- (d) 대응 함수를 bootstrap이나 recipe에 두기. realtime 어댑터는
adapters/http 타입을 import할 수 없고, 레시피 번들과 제거 드릴 범위가
바뀐다.
- `BoundedPollOperation` 자체를 제네릭으로 바꾸기. application 정책의
공개 이름이 바뀐다. 제약으로만 두면 기존 이름이 그대로다.
위험·한계:
- 기존 호출은 그대로 컴파일된다. `Value`를 직접 적은 호출은 `Operation`이
기본값이라 예전처럼 `unknown`이다. 타입을 원하면 둘 다 적거나 추론에
맡긴다(타입 주석과 9.2에 적음). 그래서 `!`를 붙이지 않았다. 단, 추론에
맡긴 호출이 descriptor 타입과 다른 입력을 실행기에 넘기고 있었다면 이제
check:types가 실패한다. 이 커밋이 잡으려는 결함이다.
- 표는 조합 코드가 따를 규칙이고 강제 수단은 없다. 템플릿은 poll
`execute` 기본 구현을 주지 않는다(리뷰 재검토 조건).
- 409·410의 `CURSOR_EXPIRED` 행은 reset 계약이 있는 기능만 해당한다.
테스트 계약에는 없어 테스트 예는 그 갈래가 없다.
- CHANGELOG 행은 이 커밋에 없다. CHANGELOG 담당이 더한다.
검증: desktop batch에서 확인.
- corepack pnpm check:types:test
- node scripts/run-vitest.ts run tests/unit/realtime/bounded-poll-coordinator.test.ts
- RED: 부모 커밋의 src에서 check:types:test가 실패한다.
bounded-poll-coordinator.test.ts의 `@ts-expect-error` 줄이 TS2578(쓰이지
않은 지시문, 입력이 `unknown`이라 `{ size: 20 }`이 통과), 그 아래
`pollAttemptResult<…>(outcome)`이 TS2345(`outcome.value`가 `unknown`).
vitest 테스트는 양쪽에서 통과한다.
- lint, check:architecture, verify:documentation
Refs: 1106/04-02
문제: 1105/16-04 수정 뒤 제품 기능 제거 드릴의 tests 잔여는 파일
이름에 기능 ID가 있거나 기능 폴더에서 import하는 파일뿐이다. 주석과 매뉴얼
01 11단계는 빠진 경우(본문에만 ID가 있는 테스트)를 test:all이 잡는다고
적었다. 그런데 test:all은 vitest 묶음이고 vitest는 tests의 *.test.ts(x)만
돈다. tests/e2e·visual 등의 *.spec.ts는 test:all도 드릴의 다른 단계도
돌리지 않는다. 그래서 `test.describe("invoice-feature", …)`처럼 본문에만
ID를 담은 spec은 드릴을 통과하고, 다음 CI의 브라우저 게이트에서 지운
라우트를 열다가 실패한다.
고른 방법: 리뷰의 (b). tests 중 vitest가 돌지 않는 Playwright spec
(`*.spec.[cm]?[jt]sx?`)은 본문도 찾는다. 다만 1105/16-04가 없앤 부분
문자열 검색으로 돌아가지 않고, 기능 ID·폴더 이름을 앞뒤가 영문·숫자·`-`가
아닌 한 이름으로만 찾는다. `"invoice-feature"`, `'invoices'`,
`/features/invoices/`는 잔여이고, product-feature를 지울 때
`generate-product-feature-index.ts`·`data-product-feature`·
`product-features`는 잔여가 아니다. vitest 테스트 본문은 그대로 찾지 않는다
(템플릿 테스트가 예시 ID를 데이터로 쓴다). 템플릿 자신의 spec에는
invoice-feature·product-feature·scaffold-feature가 한 이름으로 나오지 않는다
(git grep 0건). 그래서 16-R2(invoice-feature 제거)와 FE-GATE-020
(scaffold-feature)은 그대로 통과해야 한다. 주석, 매뉴얼 01 11단계, errors.md의
판정 문장을 고쳤다.
버린 대안: (a) 문서만 고친다. 빈틈이 남는다. spec 본문을 부분 문자열로
찾는다: 짧은 ID와 템플릿 이름(`generate-product-feature-index`)이 거짓
양성을 다시 낸다. tests의 모든 비-vitest 파일(helpers, mocks, fixtures)을
찾는다: tests/helpers/runtime-capabilities-stub.ts가 주석에
"product-feature"를 한 이름으로 적어 거짓 양성이 된다. spec이 import하는
helper는 spec이 지워지면 아무 데서도 돌지 않아 해가 없다.
위험·한계: route ID나 URL만 적은 spec은 여전히 못 잡는다(03 손 목록).
다운스트림 spec이 무관한 이유로 기능 ID를 한 이름으로 적으면 거짓 양성이
난다. 1105/16-04의 남은 부분(src 경로·본문과 tests 파일 이름의 부분 문자열
검색, dist 빌드 잔여 검사)은 이 변경이 덮지 않아 그대로 두었다. 같은 이름
단위 검색으로 바꾸면 product-feature의 거짓 양성(16-R3, 20파일)은 풀리지만,
폴더 이름에 붙은 식별자(`invoices` → `InvoicesPage`)와
`<id>-helpers.test.ts` 같은 파일 이름을 놓쳐 검사가 좁아진다. 따로 정한다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/feature-residue.test.ts
corepack pnpm create:feature invoice-feature에 본문에만 ID를 적은
tests/e2e/checkout.spec.ts를 더한 뒤 corepack pnpm test:sample-removal --
--feature=invoice-feature가 fixture-id-residue로 실패, spec 없이는 통과
Refs: 1106/16-01
문제: 문서를 복사하지 않는 capability 드릴 셋은 `REMOVAL_FIXTURE_DOCUMENT_TESTS`
의 파일을 통째로 지운다. 문서를 읽는 테스트 하나 때문에
`backend-contract-pin.test.ts`가 목록에 들어가, config와 코드만 보는 나머지
14건(pin 커밋, 답 표 사본, 생성기 사실, Envelope 판정 대조)도 그 드릴에서
돌지 않는다. `feature-tracked-files.test.ts`의 생성기 목록 검사 1건도 같다.
목록을 지키는 검사는 파일 글자에 `README.md|CHANGELOG.md|docs/`가 있는지만
봐서, `backend-contract-pin.test.ts`는 주석 한 줄로 통과했다.
고른 방법(리뷰 문서 ⓐ+ⓑ):
- 6.1 표를 읽는 테스트를 `backend-contract-pin-document.test.ts`로 옮기고
목록에는 그 파일을 둔다. pin 파일은 목록에서 빠져 모든 드릴에서 돈다.
새 파일은 pin에서 문서 경로만 읽고, 그 경로가 `docs/` 아래인지 확인한다.
- `feature-tracked-files.test.ts`의 문서와 무관한 1건을
`feature-tracked-file-rewrites.test.ts`로 옮긴다. 남은 두 건은 모두 문서를
읽어 그 파일은 목록에 남는다(`create-feature.ts`의 참조도 그대로 맞다).
- 목록 검사는 Babel로 파일을 파싱해 코드의 문자열·템플릿 리터럴에 문서
경로가 있는지 본다. 주석은 세지 않는다. 주석만 있는 소스를 거절하는지
자체 테스트를 더했다.
- 6.1 대조를 가리키던 `external-contract-runtime.ts` 주석과 계약 문서 한
줄을 새 파일 이름으로 고쳤다.
버린 대안: capability 드릴이 계약 문서 하나만 복사하기. 문서 테스트가
늘 때마다 복사 목록이 늘고, 그 드릴이 "문서 없이"를 증명한다는 전제가
흐려진다. 목록 검사만 고치기는 빠지는 범위가 그대로다.
위험·한계:
- 목록 검사는 파일 단위다. 파일 안의 모든 테스트가 문서를 읽는지는 기계로
보지 않는다. 목록 주석에 규칙을 적었다.
- 검사는 코드에 문서 경로 문자열이 있는지 본다. 그 문자열로 실제로 읽는지는
보지 않는다.
- 이 노트북에서는 실행하지 못했다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/removal-fixture.test.ts tests/unit/backend-contract-pin.test.ts tests/unit/backend-contract-pin-document.test.ts tests/unit/feature-tracked-files.test.ts tests/unit/feature-tracked-file-rewrites.test.ts
check:types, lint, verify:documentation, ci:gate FE-GATE-020(capability
드릴 셋의 unit 실행에 pin 14건이 나오는지)
Refs: 1106/12-01
문제: 0929/03-03의 두 가드(재전송 버튼 canResend, 같은 입력 재제출 거절)가
intent의 키 유무로만 가른다. 뮤테이션 정책은 키 여부만 실어서 훅이 NEVER와
IDEMPOTENT를 가를 수 없다. 그래서 IDEMPOTENT 쓰기(손으로 쓴 PUT·DELETE)도
결과 불명 뒤 재전송 버튼이 없고 같은 입력 저장이 UNKNOWN_EFFECT_PENDING으로
거절된다. 출구는 사실을 모르는 "변경됨으로 확인"이나 새로고침뿐이다. 매뉴얼은
IDEMPOTENT를 "여러 번 적용해도 결과가 같다"로 적고, 실행기도 보낸 뒤에
다시 보낸다.
고른 방법(리뷰 03-03 대안 (a)): commandMutationIdentity가 resendSafe
(KEYED 또는 IDEMPOTENT)를 함께 준다. BoundMutation에 선택 칸 resendSafe를
더했다(추가만). 훅은 admission마다 resendable(키가 있거나 정책이
resendSafe)을 적고, 두 가드가 키 대신 그 값을 본다. 칸이 없는 손으로 쓴
정책은 지금처럼 키 유무로 간다. NEVER의 재전송 금지와 같은 입력 거절은
그대로다. 매뉴얼 01·02와 런북 6.3-4에 IDEMPOTENT 행을 적었다.
버린 대안: 문서만 고치기(회복 경로가 그대로 불편하다), IDEMPOTENT에도 키를
붙이기(백엔드가 키를 읽지 않으면 의미가 없고 실행기가
UNEXPECTED_IDEMPOTENCY_KEY로 거절한다).
위험·한계: commandMutationIdentity의 반환 객체에 칸이 하나 늘었다. 그 값을
toEqual로 비교하던 테스트는 칸을 더해야 한다(이 repo는 1곳을 고쳤다).
IDEMPOTENT로 잘못 선언한 쓰기(백엔드가 실제로는 중복을 막지 못함)는 이제
결과 불명 뒤 사용자가 다시 보낼 수 있다. 선언의 정확성은 기능 작성자
몫이다(02 결정표 3절). 템플릿 안에는 IDEMPOTENT 쓰기 소비자가 없다.
CHANGELOG 행은 문서 담당이 적는다.
검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/component/application-mutation-admission.test.tsx
tests/unit/command-mutation-identity.test.ts
Refs: 1106/03-03
문제: a11y.json의 notChecked는 접근성 spec이 남긴 기록만으로 정해졌다.
기록이 없으면 "검사함"이었고, 어느 라우트에 기록이 있어야 하는지는 spec
말고 아무도 몰랐다. 리뷰 11-R2에서 실패 화면 분기의 기록 호출 reason을
null로 바꾸자 라우트 test 10건, write-a11y-report.ts, 증거 schema가 모두
통과하고 a11y.json이 상세 라우트를 scope(통과)에 넣고 notChecked: []를
적었다. 1103/11-01이 고친 거짓 주장이 한 줄로 돌아온다. 같은 실행 뒤 지난
실행의 기록 파일도 디렉터리에 남아 있었다.
고른 방법: 리뷰의 (다)와 기록 초기화.
- scripts/lib/a11y-data-state.ts의 oneResourceReadRoutes가 설치된
descriptor만으로 "실패 화면으로만 볼 수 있는 라우트"를 찾는다. 로그인이
필요한 라우트의 paramsSchema가, 경로 파라미터가 있고 빈 목록을 거부하는
GET의 입력 스키마일 때다. GET 쪽 규칙은
tests/e2e/support/installed-api-answers.ts가 답하는 규칙과 같다.
참조 기능 상세와 create:feature --with-create 상세는 GET과 같은
<Pascal>Params를 쓰므로 이 규칙에 든다.
- write-a11y-report.ts는 그 라우트가 기록(notChecked)에 없으면
`a11y.json not written:`과 라우트·operation을 찍고 rc=1로 끝난다.
a11y.json은 쓰지 않는다. test:a11y(FE-GATE-009)가 실패한다.
- accessibility.spec.ts의 라우트 test는 시작할 때 자기 기록을 지운다.
기록 호출에 닿지 못한 실행이 지난 실행의 기록을 그대로 쓰지 않는다.
엔진 셋이 같은 파일을 쓰지만 각 엔진은 지운 뒤에만 쓰고, 실행 중에
기록을 읽는 곳이 없어 순서가 섞여도 결과가 같다.
- 단위 테스트: 가짜 descriptor로 규칙(목록·경로 아래 목록·DELETE·공개
라우트 제외)과 거절(null 기록은 거절, 기록이 있으면 통과, 기대 밖 기록은
허용). 참조 기능 테스트가 실제 descriptor에서 REFERENCE_RESOURCE_DETAIL
하나가 나오는지 본다. 이 줄이 없으면 규칙이 아무것도 찾지 못해도
모른다. 참조 기능과 함께 지워진다.
- 11-R2 diff는 그대로 적용된다(문맥 줄 유지, 4줄 offset).
버린 대안:
- (나) 두 상태 모두 기록하고 기록 없는 라우트를 실패: 기록 삭제는 잡지만
reason을 null로 바꾸는 11-R2는 못 잡는다. 실행 경계(TEST_RUN_ID)도
정해야 한다.
- 증거 schema(release-artifacts.ts)에서 검사: schema 모듈이 기능
런타임 전체(top-level await)를 불러야 하고, 그 모듈을 쓰는 스크립트가
많다.
- spec 안에서 기록을 다시 읽어 대조: 같은 test의 두 줄을 서로 대조할
뿐이고, 시작 시 초기화와 엔진 동시 실행이 겹치면 거짓 실패가 난다.
- 기록 호출의 모양을 바꿔 사실(읽은 operation)을 적고 report가 판정:
11-R2 변이 자리가 사라져 리뷰 변이로 확인할 수 없다.
위험·한계: 방향은 하나다. 규칙이 찾은 라우트가 기록에 없으면 실패하고,
규칙이 못 찾는 라우트를 spec이 notChecked로 적는 것은 덜 주장하는 쪽이라
받는다. paramsSchema가 GET 입력과 다른 상세 페이지(손으로 쓴 기능)는
규칙이 찾지 못해 기록만으로 정해진다(이전과 같다). 공개 라우트는 spec이
API에 답하지 않으므로 이 규칙 밖이다. write-a11y-report.ts가 기능 런타임
전체를 불러온다(check:registries와 같은 경로). check:types:node가 그
그래프를 node 설정으로 검사한다. 노트북에서 아무것도 실행하지 않았다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/a11y-report.test.ts
tests/features/reference-feature/reference-contract.test.ts
11-R2 변이와 기록 줄 삭제 변이에서 playwright(chromium, @a11y /) 뒤
node scripts/write-a11y-report.ts rc=1, 변이 없이 rc=0. corepack pnpm
test:a11y
Refs: 1106/11-01
문제: KEYED 결과 불명 요청을 같은 키로 다시 보냈는데 그 시도가 쓰기 전
거절(429, 엣지 rate limiter의 503 RATE_LIMIT_*, 401)이나 보내기 전 실패
(NOT_STARTED)로 끝나면, 훅이 그 판정을 논리 요청 전체의 판정으로 써서
결과 불명과 intent를 버린다. 폼은 retry-later가 되고 다음 저장이 새 키로
나간다. 첫 요청이 적용됐으면 같은 항목이 둘 생긴다. 재전송의 NOT_APPLIED는
그 시도만 증명한다. 백엔드 http-contract.md §2와 런북 6.3-4는 결과 불명에
새 키를 금지한다(리뷰 실험 03-R1 X1~X3·X5: keys key-1, key-1, key-2).
고른 방법(결정 D10, 메인 세션, 2026-11-06: 리뷰 03-01 대안 (a)):
- 훅(application-query.ts submit): 결과 불명 intent를 다시 쓴 시도가
NOT_APPLIED·NOT_STARTED로 끝나면 새 admission을 UNKNOWN으로 되돌리고 그
intent와 키를 남긴다. 실패는 그대로 돌려준다. Retry-After는 MAYBE_APPLIED와
같이 다음 재전송의 대기 시각이 된다. 낙관적 층은 rollback 대신
markUncertain이다(첫 요청이 적용됐을 수 있다). 훅 안의 보내기 전 예외
(.catch, NOT_STARTED)도 같다. 이 경우 충돌 상태는 세우지 않는다. 화면은
결과 불명을 먼저 보여야 한다. 처음 보내는 요청의 NOT_APPLIED, 재전송의
성공·APPLIED_CONFIRMED, scope가 바뀐 경우는 지금처럼 정리한다.
- 폼은 (i)을 골랐다: use-app-form.ts resendUnknown이 그런 결과에서
unknownSubmissionRef를 지우지 않고 result를 effect-unknown으로 둔다. 문구
하나("form.resendLater": "잠시 뒤 같은 요청으로 다시 보내 주세요")를
formErrors에 싣고 feedback으로 포커스를 옮긴다. 이유: 폼은 이미 그 ref로
저장을 막는다(submitForm). 결과 불명 화면(확인·같은 키로 다시 보내기)이
그대로 남아 다음 행동이 재전송이다. (ii)는 useAppForm이 코디네이터 상태를
받는 새 옵션이 필요하다. 폼과 훅을 새로 묶는 일이라 지난 라운드 3.5 (B)로
미룬 설계 변경이다. 401은 D-2대로 다시 로그인이 먼저다.
버린 대안: 표에서 rate-limit 503을 다시 MAYBE_APPLIED로(429·401·NOT_STARTED가
남고 1105/03-02의 이득을 잃는다), 생성 페이지의 "다시 시도"만 고치기(생성
기능만 덮는다).
위험·한계: 재전송이 rate limit에 막힌 동안 결과 불명 화면이 남는다. 다시
보내기는 Retry-After(상한 5초)를 기다린다. 폼 밖에서 submit을 부른 같은
입력 재저장이 NOT_APPLIED로 끝나면 훅은 키를 지키지만 폼은 retry-later를
보인다. 그때 "다시 시도"도 같은 키로 간다. 새 문구가 초기 JS를 조금
늘린다(check:bundle). CHANGELOG 행은 문서 담당이 적는다.
검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/component/application-mutation-admission.test.tsx
tests/component/form-foundation.test.tsx, 리뷰 실험 03-R1 패치를 이 커밋에
적용해 X1~X3 keys [key-1,key-1,key-1], X5 세 번째 요청 없음 또는 key-1.
Refs: 1106/03-01
문제: reconnect coordinator는 `attempt`·`waitClosed`가 던지면
PROVIDER_UNAVAILABLE(CONNECT·RECEIVE, retryable)로 보고 backoff로 다시
시도한다. 05330e3 뒤 poll은 같은 던짐을 PROTOCOL_MISMATCH로 끝낸다. 이
차이는 그 커밋 본문에만 있고 타입 주석과 설계 13.1에는 없다. repo의 SSE
bridge 예(`sseAttempt`)는 `attempt` 안에서 연결을 만든다. 그래서
endpoint 설정 오류가 요청 0번, attempt 3번, PROVIDER_UNAVAILABLE
(EXHAUSTED)로 끝나 서버 장애로 보인다(리뷰 실험 04-R2).
고른 방법: 리뷰 선택지 (c). 동작은 그대로 두고 규칙을 적는다.
- `attempt` 주석: 던짐은 transport 실패로 재시도된다. 설정 검사는
`attempt` 밖, 조합 코드가 transport를 만들 때 한다. poll과 다른 이유도
적었다. `waitClosed` 주석: RECEIVE로 같은 규칙.
`classifyClosed`·`confirmTransportBarrier` 주석: 던짐은
PROTOCOL_MISMATCH로 끝나고 재시도하지 않는다.
- 설계 13.1 PROVIDER_UNAVAILABLE·PROTOCOL_MISMATCH 행에 같은 규칙을 적었다.
- 테스트 bridge `sseAttempt`는 만들어질 때 연결 설정을 한 번 검사한다.
연결은 attempt마다 새로 만든다. session `close`가 연결을 끝내므로 한
연결을 여러 attempt에 쓸 수 없다.
- 규칙을 고정하는 테스트를 더했다. attempt·waitClosed 던짐은 3회 재시도 뒤
PROVIDER_UNAVAILABLE(EXHAUSTED), classifyClosed 던짐은 1회로
PROTOCOL_MISMATCH, bridge의 http endpoint는 만들 때 TypeError(fetch 0).
버린 대안:
- (b) reconnect도 던짐을 PROTOCOL_MISMATCH로 끝내기. 연결 실패를 던지는
라이브러리를 감싼 transport가 첫 실패에서 run을 끝내게 되는 공개 동작
변경(BREAKING)이다. 리뷰도 지금 동작이 회복에 유리하다고 봤다.
05330e3이 poll에서 (c)를 버린 이유("결과로 구분한다")는 이번 완료
기준에 없다.
- 연결 하나를 bridge에서 만들고 attempt마다 read만 하기. 위와 같이
session `close`가 연결을 닫아 다음 read가 CLOSED가 된다.
위험·한계:
- 동작이 같으므로 조합 코드가 `attempt` 안에서 연결을 만들면 설정 오류는
여전히 서버 장애로 보인다. 주석과 13.1은 모르고 쓰는 경우만 줄인다.
- 매핑 오류 같은 나머지 던짐도 그대로 재시도되고 원인 예외는 남지 않는다
(닫힌 관측 어휘).
- CHANGELOG 행은 이 커밋에 없다. CHANGELOG 담당이 더한다.
검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/realtime/realtime-reconnect-coordinator.test.ts
- RED 없음. 동작을 바꾸지 않는 커밋이라 새 테스트는 부모 커밋에서도
통과한다. 규칙을 고정하는 테스트다.
- check:types, lint, verify:documentation
Refs: 1106/04-01
문제: 두 테스트가 검사 대상을 "파일이 있으면"으로 정한다.
- `playwright-run-isolation.test.ts`는 capabilities 설정이 있을 때만
그 설정의 검사 8개를 정의한다(`existsSync`). browser-file-storage
드릴 사본에서 33개가 25개로 줄었는데 skip 보고가 없다. 템플릿에서
설정 이름을 바꾸고 테스트의 문자열만 놓쳐도 같이 빠진다.
- `vite-build-inputs.test.ts`는 목록 소비자 둘을 `existsSync`로 거른다.
어느 제거 목록에도 없는 `product-feature-selection-build.test.ts`의
이름이 바뀌어도 검사가 빈 반복으로 통과한다.
- 주석의 skip 차단 ID가 0929/10-04로 틀렸다. 1101/10-04다.
고른 방법(리뷰 문서 ⓐ):
- capabilities 검사 8개를 `playwright-capabilities-run-isolation.test.ts`로
옮기고 설정을 이름으로 import한다. browser-file-storage 드릴이 설정과
이 파일을 이름으로 함께 지운다. 같은 드릴이 `ci-workflow-generation`
테스트를 지우는 방식이다. `force` 없이 지워, 이름이 바뀐 파일은 드릴이
그 자리에서 멈춘다.
- 두 파일이 같은 검사를 쓰도록 불러오기·포트·결과 폴더 검사를
`tests/helpers/playwright-run-isolation.ts`로 뺐다. 단언은 그대로다.
- `vite-build-inputs`는 빌드 테스트를 늘 읽는다. 측정 스크립트는 그
파일을 가진 제거 가능 기능(`removable-template-features.ts`)이 설치돼
있을 때(feature-module.ts가 있을 때, verify:documentation과 같은 규칙)
읽는다. 그 소유 기능이 없으면 실패한다. 기능 ID를 테스트에 쓰지 않는
것은 샘플 드릴의 residue 검사가 `src`·`tests`의 샘플 이름을 잡기 때문이다.
- 틀린 ID 주석은 옮긴 검사와 함께 없어지고, 새 파일 머리말에 1101/10-04로
적었다.
버린 대안: 드릴이 표시를 넘기고 테스트가 읽는 방식(ⓑ). 드릴과 테스트
사이 계약이 늘고, capability를 지우는 제품이 테스트를 고쳐야 한다. 주석
ID만 고치기(ⓒ)는 공백이 남는다.
위험·한계:
- 테스트 수는 템플릿 33개(25 + 8)로 같다. browser-file-storage 사본에서는
25개가 돌고 8개는 파일째 지워진다(드릴 코드에 적힘).
- 측정 스크립트의 조건은 여전히 파일 존재(소유 기능의 feature-module.ts)다.
대상이 지울 수 있다고 등록된 소유자로 바뀌었다.
- 이 노트북에서는 실행하지 못했다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/playwright-run-isolation.test.ts tests/unit/playwright-capabilities-run-isolation.test.ts tests/unit/vite-build-inputs.test.ts
이름 바꾸기 변이 둘(capabilities 설정, product-feature-selection-build
테스트), check:types, lint, ci:gate FE-GATE-020
Refs: 1106/10-01
문제: FE-REG-SCHEMA 행의 direction·unknownFieldPolicy는 타입에서 선택
칸이다. tests/unit/schema-metadata-policy.test.ts는 행이 값을 적지 않으면
그 자리를 건너뛰었다(direction의 `declared === undefined`, 정책의
`if (declared === undefined) return []`). 1105/07-02는 RESPONSE 행의
정책이 REJECT_UNKNOWN으로 바뀔 때만 breaking으로 본다. 그래서 손으로 쓴
응답 행이 두 칸을 빼고 들어오면, 뒤에 응답 DTO를 .strict()로 바꿔도 행이
바뀌지 않아 check:registries는 아무것도 보지 않고 정책 테스트도 건너뛴다.
백엔드가 응답에 필드 하나를 더하면 그 API가 SCHEMA_MISMATCH로 실패한다.
고른 방법: 리뷰의 (A). descriptor의 입력·응답·실패 검증기(`slots`)로 쓰인
스키마의 행이 두 칸을 적지 않으면 두 테스트가 실패로 센다. 메시지는
`row states no direction, used as <방향>`과
`row states no unknownFieldPolicy, validator <탐침 결과>`다. 행이 아예 없으면
같은 메시지가 나오고, boundary 테스트도 `no FE-REG-SCHEMA row`로 실패한다.
템플릿 HTTP 행과 생성기가 쓰는 행(create-feature.ts, create-feature-
write-slice.ts)은 이미 두 칸을 적어 통과한다. 라우트에만 쓰이는 행
(NotFoundSplat)은 slots에 없어 그대로 두 칸이 없어도 된다.
매뉴얼 01 4단계와 errors.md에 규칙과 메시지를 적었다.
버린 대안: (B) governance가 api-* 경계 행에 두 칸을 필수로 둔다. 경계별
필수 칸 규칙이 governance에 없어 분류기 변경과 기준선 재승인이 필요하다.
타입에서 두 칸을 필수로 만들면 route 전용 행까지 바뀌고, src/contracts
export의 모양이 바뀐다.
위험·한계: 다운스트림이 두 칸 없는 HTTP 행을 가졌다면 동기화 뒤 test:unit이
실패한다. 메시지대로 두 칸을 적으면 된다. 고친 곳이 검사(테스트 파일)
자신이라 RED는 테스트 파일만으로 만들 수 없다. 참조 응답 행에서 두 칸을
지운 변이로 확인한다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/schema-metadata-policy.test.ts
(변이 없이 통과, ReferenceResourcePayload 행의 두 칸을 지운 변이에서 두
테스트 실패)
Refs: 1106/07-02
문제: control cache의 active pointer entry는 있는데 저장된 본문이 다시
쓰기 전까지 계속 읽히지 않으면(blob 손실 등) Cache Storage 관리가 모두
멈춘다. readActivePointer는 이 실패를 UNAVAILABLE/RETRY(또는
NOT_READABLE/REOPEN)로 돌려주고 CORRUPT_DATA로 보지 않는다. activation은
CORRUPT_DATA 밖의 pointer 실패에서 멈추고, cleanup·inspect·조회도 같은
실패에서 멈춘다. pointer를 쓰는 곳은 activation 하나라서 RETRY를
지켜도 돌아오지 않는다. 돌아오는 길은 adapter 밖에서 control cache를
지우는 것뿐이다. 리뷰 실험 02-R1 X3이 이것을 보였다.
고른 방법: activateRelease에 선택 옵션 replaceUnreadablePointer를 둔다.
true면 이전 pointer를 읽지 못한 이유와 상관없이, 손상 pointer와 같은
0929/02-01 경로로 검증된 후보를 rollback 목록 없이 덮어쓴다. 기본값은
지금처럼 멈춤이라 "일시 오류 하나로 rollback 목록을 잃지 않는다"는
보존 조건이 지켜진다. 포트 주석, 설계 문서 8.3절, 운영 문서에 언제
쓰는지와 rollback 목록을 잃는다는 것을 적었다.
버린 대안: (가) 문서에 "control cache를 지우고 다시 activate"만 적기.
제품이 adapter 밖 코드로 소유 cache 이름을 알고 지워야 하고, 그동안
조회가 pointer 없음으로 바뀐다. (다) 연속 N회 실패를 손상으로 보기.
실패 횟수를 저장해야 하고, 긴 일시 오류에서도 rollback 목록을 잃는다.
위험·한계: 옵션을 켜면 일시 오류에서도 rollback 목록을 잃고, 다음
cleanup이 새 활성 release 밖의 owned release cache를 모두 지운다. 그래서
기본값으로 두지 않았다. 일시와 지속을 가르는 판단은 운영자 몫이다.
포트에 선택 칸이 하나 늘었다. 호출부·구현부 모두 호환이라 breaking이
아니다. CHANGELOG [계약] 행은 CHANGELOG 담당에게 남긴다.
1105/02-02의 남은 부분(release marker 본문이 계속 읽히지 않으면 stage가
marker를 다시 쓰지 않는다)은 이 변경으로 풀리지 않는다. marker는 release
cache 안의 entry라 stage 경로를 바꿔야 한다. 범위 밖으로 둔다.
service-worker-pwa 레시피 번들(여유 306 B)에 수십 B가 더해진다.
실제 브라우저에서 pointer 본문 읽기 실패가 지속되는지는 확인하지
못했다(리뷰 5절 미검증과 같다).
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/public-response-cache-repair.test.ts
RED(이 커밋의 테스트 + 부모 src): "replaces a pointer whose body stays
unreadable when the activation asks to (1106/02-01)"가 옵션을 준
activation에서 실패한다. 부모는 옵션을 모르므로 UNAVAILABLE/RETRY를
돌려주고 pointer를 다시 쓰지 않는다. 그 앞의 멈춤 단언(X3와 같은
결과)은 부모에서도 통과한다. 일시 오류 테스트 "still stops activation
when the pointer read fails transiently"는 바뀌지 않았고 통과해야 한다.
Refs: 1106/02-01
문제: 짝 백엔드 Fileserver는 검증기가 거절한 업로드를 202 성공
Envelope(state REJECTED)로 답한다. client는 이 답을 FILE_REJECTED
실패로 바꾸는데, readSuccessEnvelope가 meta.traceId를 버려서 실패에
traceId가 없다. 같은 client의 Envelope 실패는 traceId를 싣는다
(1105/01-03). 서버가 정상으로 답해 trace 값이 손에 있는데도, 지원
담당이 이 거절을 서버 로그나 REJECTED 레코드와 잇지 못한다.
고른 방법: readSuccessEnvelope가 readFailureEnvelope처럼 meta.traceId가
있으면 traceId로 함께 돌려준다. Fileserver client는 202 REJECTED
실패에 그 값을 싣는다. V3 실행기는 value와 page만 읽으므로 동작이
같다. 매뉴얼 7절 결과 읽기 줄에 적었다.
버린 대안: fileserver-upload가 successEnvelopeSchema를 직접 파싱하면
Envelope 읽기가 backend-envelope.ts 밖으로 갈라진다. traceId만 읽는
함수를 따로 두면 같은 답을 두 번 파싱한다.
반환 칸이 늘어 readSuccessEnvelope 결과를 toEqual로 보는 테스트 두
곳(tests/runtime-schema/http-schema.test.ts,
tests/unit/a11y-api-answers.test.ts)의 기대값에 traceId를 더했다.
기대를 넓힌 것이 아니라 새 칸의 값까지 고정한 것이다.
위험·한계: 거절 이유는 여전히 없다. 프론트로는 고칠 수 없어
백엔드로 넘긴다.
- 사실(백엔드 45d2a478): FinalizeUploadApplicationUseCase
#applyNonAcceptVerdict는 REJECT 판정의 code(FILE_TOO_LARGE,
DIGEST_MALFORMED, 제품 검증기 code 등)를 FileRecordMutation.failure로
레코드의 lastErrorCode에만 쓴다. FileUploadController#created는
UploadedFileResponse 7칸(fileId, state, filename, mediaType, size,
sha256, etag)을 202로 답한다. 이유 칸이 없다.
- 요청: REJECT를 실패 Envelope(422, error.code = 판정 code,
retryable false)로 답하거나, 202 REJECTED 응답에 판정 code 칸을
더한다. 앞의 것이면 프론트의 기존 422 경로가 code와 traceId를
그대로 싣고 NOT_APPLIED로 읽는다. 그때 FILE_REJECTED 분기는 지운다.
- CHANGELOG의 "백엔드로 넘김" 목록에 이 항목을 더하는 일은 CHANGELOG
담당에게 남긴다.
실제 배포 응답의 성공 meta에 traceId가 있는지는 백엔드 문서
(docs/web/http-contract.md §1 meta 키)와 EnvelopeBodyAdvice 코드로만
확인했다. backend-envelope.ts는 초기 번들에 있어 초기 JS가 수십 B
늘 수 있다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts tests/runtime-schema/http-schema.test.ts tests/unit/a11y-api-answers.test.ts
RED(이 커밋의 테스트 + 부모 src): "reads 202 REJECTED as a refused
file, not as a broken answer"가 traceId "trace-1"이 없어 실패한다.
"reads data, and a dropped data key as null"과 "answers an Envelope
list read with an empty list inside the Envelope"는 결과에 traceId
칸이 없어 실패한다.
Refs: 1106/01-01