docs(ledger): 흔들린 시험 기록을 두고 시간·순서 단언 규칙을 가리킨다
흔들린 시험을 적는 곳이 없다. 2026-11-12~13 이틀에 프론트 흔들림이 여섯 건이었다. 재실행으로 통과시킨 것은 세션 노트에만 남았다. 같은 모양(첫 렌더 5초 창, 잠금 순서 가정)이 다시 들어와도 리뷰 기준에 막을 줄이 없다. docs/ledger/flaky-tests.jsonl을 두고 여섯 건을 첫 줄들로 넣는다. 칸은 design-docs ci/manual.md 8.5절이다(date·test·category·first_run·verdict· quarantined_until·fixed_by). 여기에 대응하는 표를 docs/ledger/README.md 「흔들림 기록」에 둔다. 이 파일도 estimates.jsonl처럼 더하기만 하고 .gitattributes merge=union으로 합친다. README 지워도 되는 파일 표와 docs/README.md 지도에 넣었다. testing.md 5절 조사 절차에 6번(기록)을 더했다. 리뷰 기준 2절 「헷갈리는 경우」에 벽시계 상한·시작 순서 단언을 구조적 위험으로 적고, gates.md 3절에서 둘을 가리킨다(ci/manual.md 8.4절). 버린 대안: scripts/verify.sh docs가 이 파일의 칸과 범주까지 검사하게 하는 안. 이번 범위(계획 FLAKY-1) 밖이라 뒤로 미뤘다. 지금은 손으로 맞춘다. 위험·한계: platform-overview.spec.ts:48(WebKit)은 원인 조사 전이다. 범주는 5초 창에서 실패한 꼴만 보고 fixed-time으로 적었다. 검증: scripts/verify.sh docs(노트북) OK, desktop verify:documentation.
This commit is contained in:
@@ -1 +1,2 @@
|
||||
docs/ledger/estimates.jsonl merge=union
|
||||
docs/ledger/flaky-tests.jsonl merge=union
|
||||
|
||||
@@ -244,6 +244,7 @@ export CI=true VITE_COMMIT_SHA="$(git rev-parse HEAD)" VITE_BUILD_ID=local-ci-1
|
||||
| `docs/history/` | 끝난 작업의 계획서와 증거. 2026-09-25 리뷰 수정 라운드의 요구사항과 작업 목록도 여기 있다 |
|
||||
| `docs/reviews/` | 리뷰와 리뷰 가이드 포인터. `docs/reviews/adapters/`는 남긴다: `check:adapter-inventory`(FE-GATE-010)가 그 안의 `INVENTORY.md`를 읽고, 그 행이 옆의 adapter 리뷰로 링크하며, `docs/operations/adapter-remediation-ledger.md`가 그 리뷰를 인용한다 |
|
||||
| `docs/ledger/estimates.jsonl` | 템플릿 자신의 작업 예측·실측. 줄을 비우고 자기 프로젝트 줄을 쌓는다(`docs/ledger/README.md`) |
|
||||
| `docs/ledger/flaky-tests.jsonl` | 템플릿 자신의 흔들린 시험 기록. 줄을 비우고 자기 프로젝트 줄을 쌓는다(`docs/ledger/README.md`) |
|
||||
| `PRODUCT.md` | 디자인 도구가 읽는 템플릿 자체의 제품 맥락(사용자, 목적, 원칙). 제품 것으로 바꾼다 |
|
||||
|
||||
기능은 이 목록에 없다. 기능 폴더만 지우면 테스트, 정책 항목, CI 스크립트가 남아 게이트가 실패한다.
|
||||
|
||||
+1
-1
@@ -37,7 +37,7 @@
|
||||
| --- | --- |
|
||||
| `work/` | 작업 매뉴얼: 새 기능, 리뷰·수정·리팩터링, 조사·설계, 문서, 운영, 일 나누기의 playbook. `work/reference/`에 게이트·구조·테스트·리뷰 기준과 결정 색인, `work/evidence.md`에 매뉴얼 규칙의 근거 기록 |
|
||||
| `manual/` | 개발 매뉴얼: 새 기능 하나를 더하는 0~11단계, 결정표, 기능 폴더 밖 파일, 짝 백엔드에 붙이기. `manual/reference/`에 명령 인자, 전역 ID, 패턴, 오류 메시지 |
|
||||
| `ledger/` | 작업 예측·실측 장부(`ledger/estimates.jsonl`, 형식은 `ledger/README.md`) |
|
||||
| `ledger/` | 작업 예측·실측 장부(`ledger/estimates.jsonl`)와 흔들린 시험 기록(`ledger/flaky-tests.jsonl`). 형식은 `ledger/README.md` |
|
||||
|
||||
### 현재 계약
|
||||
|
||||
|
||||
@@ -13,6 +13,7 @@
|
||||
- p30·p50·p80은 그 값 안에 끝날 확률이 30%·50%·80%라고 보는 세 값이다. p30이 도전값, p80이 안전값이다.
|
||||
- 시간의 기준은 작업 중 시간이다. 끝 보고 뒤 다음 지시를 기다린 시간은 넣지 않는다. 배수는 근거(바꿀 파일 수, 검증 대기)가 있을 때만 쓴다.
|
||||
- 위임 대조용 장부(design-docs `delegation-loop/ledger.jsonl`)는 그대로 둔다. 그 줄의 예측·실측 칸은 이 파일의 `task`를 가리킨다.
|
||||
- 흔들린 시험은 `docs/ledger/flaky-tests.jsonl`에 따로 쌓는다(아래 「흔들림 기록」).
|
||||
|
||||
## 줄의 칸
|
||||
|
||||
@@ -47,3 +48,17 @@
|
||||
| `why` | 문자열 | 예측이 틀렸으면 이유 한 줄 |
|
||||
|
||||
`retro`: `cause`(지시 모호 · 착수 전 조사 부족 · 아키텍처 경직 · 검증 대기 · 외부 대기 · 범위 변경 · 예측 근거 없음), `level`(`architecture` · `gate` · `instructions` · `user`), `note`, `ref`(고친 커밋이나 문서).
|
||||
|
||||
## 흔들림 기록
|
||||
|
||||
`docs/ledger/flaky-tests.jsonl`에 흔들린 시험 하나마다 JSON 한 줄을 더한다. 칸과 처리 절차의 정본은 design-docs `ci/manual.md` 8.3·8.5절이다. 이 파일도 더하기만 하고 `merge=union`으로 합친다.
|
||||
|
||||
| 칸 | 뜻 |
|
||||
| --- | --- |
|
||||
| `date` | 처음 본 날(`YYYY-MM-DD`) |
|
||||
| `test` | spec 파일:줄 또는 시험 파일:줄 |
|
||||
| `category` | `fixed-time` · `concurrency-order` · `resource-io` · `test-order` · `external` |
|
||||
| `first_run` | 처음 본 runner run 번호, desktop이면 로그 경로 |
|
||||
| `verdict` | 판정 결과(예: 「8회 중 1회 실패」, 「재현 안 됨」)와 원인 |
|
||||
| `quarantined_until` | 격리했으면 기한, 아니면 빈 값 |
|
||||
| `fixed_by` | 고친 PR(`프론트 #47` 형식), 아직이면 빈 값 |
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
{"date": "2026-11-12", "test": "tests/e2e/old-tab-chunk-recovery.spec.ts:213", "category": "resource-io", "first_run": "127", "verdict": "runner 1회 실패. desktop 계측 e2e 8회 중 같은 원인 2회(Firefox 첫 localStorage 접근이 프로필 디스크를 기다림)", "quarantined_until": "", "fixed_by": "프론트 #47"}
|
||||
{"date": "2026-11-13", "test": "tests/e2e/preload-use.spec.ts:111", "category": "resource-io", "first_run": "desktop scripts/verify.sh merge(트리 0f927214)", "verdict": "1회 실패, 같은 트리 재실행 통과. 원인은 위와 같음", "quarantined_until": "", "fixed_by": "프론트 #47"}
|
||||
{"date": "2026-11-13", "test": "tests/e2e/platform-overview.spec.ts:11", "category": "resource-io", "first_run": "/tmp/claude-gates/w2fe2-fr3", "verdict": "desktop 계측 e2e 8회 중 1회 실패(앱 부트 4.3초). 원인은 위와 같음", "quarantined_until": "", "fixed_by": "프론트 #47"}
|
||||
{"date": "2026-11-13", "test": "tests/e2e/generated-feature.spec.ts:378", "category": "resource-io", "first_run": "266", "verdict": "main run FE-GATE-009 [firefox] 1회 실패(로그인 화면 5초 대기). 원인은 위와 같음", "quarantined_until": "", "fixed_by": "프론트 #47"}
|
||||
{"date": "2026-11-13", "test": "tests/unit/shared-fixture-builds.test.ts:60", "category": "concurrency-order", "first_run": "235", "verdict": "runner 1회 실패. 첫 mkdir 지연으로 결정적 재현(waiter가 잠금을 먼저 잡음)", "quarantined_until": "", "fixed_by": "프론트 #46"}
|
||||
{"date": "2026-11-13", "test": "tests/e2e/platform-overview.spec.ts:48", "category": "fixed-time", "first_run": "/tmp/claude-gates/w2fe2-fr6", "verdict": "[webkit] desktop 계측 e2e 8회 중 1회 실패(「미선택」 4개가 5초 안에 0개, 앱 부트는 1.08초). 원인 조사 전", "quarantined_until": "", "fixed_by": ""}
|
||||
@@ -69,6 +69,8 @@ release 단계 게이트는 merge 단계에 없다. 그래서 lab 게이트 회
|
||||
|
||||
**가끔 떨어지는 게이트.** 다시 돌려 통과시킨 결과를 "통과"로 쓰지 않는다. 실패한 회차를 그대로 적고 원인을 찾는다([testing.md](testing.md) 5절). "세 번째 실행에서 통과"로 적혔던 FE-GATE-008의 두 실패는 둘 다 테스트 결함이었다. 원인을 고친 뒤에는 같은 게이트를 연속으로 여러 번 돌려 실패 0을 적는다.
|
||||
|
||||
**흔들림 기록과 시간 단언.** 흔들린 시험은 처음 본 날 `docs/ledger/flaky-tests.jsonl`에 한 줄 남긴다([testing.md](testing.md) 5절 6번). 새 시험이 벽시계 상한이나 시작 순서를 단언하면 리뷰가 막는다([리뷰 기준](review-criteria.md) 2절, design-docs `ci/manual.md` 8.4절).
|
||||
|
||||
**FE-GATE-013은 시스템 컨테이너 안에서 돈다.** provider sandbox는 systemd user manager와 bubblewrap을 쓴다. CI의 job 컨테이너에는 둘 다 없고, desktop ssh 셸은 비특권 user namespace가 막혀 있다. 그래서 계약(`config/ci/gates.json`의 `hostEnvironment`)이 이 게이트를 `scripts/run-in-system-container.sh` 안에서 돌게 하고, workflow와 `scripts/verify.sh`가 같은 길을 쓴다. 래퍼는 일회용 privileged systemd 컨테이너(`config/ci/system-container.Dockerfile`)를 띄워 작업 트리를 복사하고 root로 돌린 뒤 `artifacts/`를 되가져온다. Docker가 필요하다(CI는 runner의 dind, desktop은 호스트 Docker). 컨테이너 안에서 통과하면 다른 게이트처럼 통과로 센다(소유자 결정 2026-11-11: 조건이 되는 실행 환경을 찾아 초록으로). 컨테이너 안은 root라 「비특권 runner에서 bwrap user namespace」 조건 자체는 증명하지 않는다. 실패하면 `scripts/verify.sh parts FE-GATE-013`으로 명령마다 보고, `SYSTEM_CONTAINER_KEEP=1`이면 컨테이너를 남긴다. 호스트 시스템 설정은 바꾸지 않는다.
|
||||
|
||||
**컨테이너를 띄울 수 없는 호스트의 FE-GATE-013.** Docker가 없거나 privileged 컨테이너를 막는 호스트에서는 래퍼가 종료 코드 3으로 끝난다. 그런 호스트는 `VERIFY_HOST_ENVIRONMENT=off`를 주어 게이트를 호스트에서 돌리고 아래로 판정한다. desktop ssh 셸에서는 비특권 user namespace가 막혀 `bwrap --unshare-net`이 실패하고, `test:system`의 provider 테스트가 호스트 원인으로 떨어진다. 사전 점검(`scripts/check-system-test-prerequisites.ts`)은 이 제한을 이름으로 대며 실패한다. merge 판정에서는 이 실패를 호스트 원인으로 보고 뺀다(소유자 결정 2026-11-11에 따라 2026-11-12에 정함, [decisions.md](decisions.md) 2.2절). 뺄 수 있는 조건은 둘이고, 하나라도 어기면 merge 가능이 아니다.
|
||||
|
||||
@@ -52,6 +52,7 @@
|
||||
| 같은 사실을 여러 곳에 손으로 적었고 아직 같다 | 구조적 위험 |
|
||||
| 같은 사실의 손 사본이 이미 서로 다르다 | 확인된 결함 |
|
||||
| 수정이 템플릿 원래 상태에서만 맞다 | 결함. 지원 구성(기능 추가·확장 지점 채움)에서 재현하면 확인된 결함 |
|
||||
| PR·main 단계 시험이 벽시계 상한(「몇 ms 안에」)이나 작업 시작 순서를 단언한다 | 구조적 위험. 시계를 주입하고, 조건이 될 때까지 기다리고, 결과를 단언하게 고친다. 브라우저 첫 렌더 대기는 부하를 견디게 잡고 자원·IO 원인은 따로 고친다(design-docs `ci/manual.md` 8.4절) |
|
||||
|
||||
## 3. 심각도와 우선순위 — 이 repo의 판정 예
|
||||
|
||||
|
||||
@@ -92,6 +92,7 @@
|
||||
3. 결정적 재현을 만든다. 원인이라고 본 조건을 강제로 만들어 매번 실패하게 한다. 예: mousedown 때 앱 높이를 늘리면 세 엔진 6/6 실패, 모듈 응답을 3.5초 늦추면 WebKit 경고 2/2.
|
||||
4. 고친다. 고친 뒤 결정적 재현이 통과하고, 실제 조건 반복 실행에서 실패 0인지 본다(예: 660/660).
|
||||
5. 검사가 약해지지 않았는지 변이로 본다. 경고를 무시하게 고쳤으면, 원래 잡아야 할 것(정말 안 쓴 preload)을 여전히 잡는지 확인한다.
|
||||
6. 처음 본 날 `docs/ledger/flaky-tests.jsonl`에 한 줄 남긴다. 고치면 같은 `test`로 `fixed_by`를 채운 줄을 더한다(칸은 `docs/ledger/README.md` 「흔들림 기록」).
|
||||
|
||||
**브라우저 테스트에서 반복된 원인.**
|
||||
|
||||
|
||||
Reference in New Issue
Block a user