From 54ba35889283f3e3b8a8dbd723b92703b42f0bcf Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 26 Sep 2026 01:11:04 +0900 Subject: [PATCH] docs: hand off the maturity review fixes to another machine tasks/handoff.md records merged and pending lanes, the remaining tasks and follow-ups, and the integration procedure. tasks/lanes/ carries the lane brief and a machine-independent worktree setup script. todo.md marks the tasks already merged into this branch. Co-Authored-By: Claude Opus 5.5 --- tasks/handoff.md | 91 +++++++++++++++++++++ tasks/lanes/LANE-BRIEF.md | 80 +++++++++++++++++++ tasks/lanes/setup-lane.sh | 42 ++++++++++ tasks/todo.md | 161 +++++++++++++++++++------------------- 4 files changed, 294 insertions(+), 80 deletions(-) create mode 100644 tasks/handoff.md create mode 100644 tasks/lanes/LANE-BRIEF.md create mode 100755 tasks/lanes/setup-lane.sh diff --git a/tasks/handoff.md b/tasks/handoff.md new file mode 100644 index 00000000..259eeedd --- /dev/null +++ b/tasks/handoff.md @@ -0,0 +1,91 @@ +# 인계: 성숙도 리뷰(2026-09-25) 수정 작업 + +2026-09-26 01:10, 노트북 부하 때문에 세션을 멈추고 desktop으로 옮긴다. 이 문서만 읽고 이어서 진행할 수 있게 적었다. + +- 요구사항: `SPEC.md` (결정 D-1~D-19) +- 실행 방식: `tasks/plan.md` +- 작업 목록: `tasks/todo.md` (통합이 끝난 항목만 `[x]`) +- 레인 지시서: `tasks/lanes/LANE-BRIEF.md` (6절이 2차 레인 추가 규칙) +- worktree 준비: `tasks/lanes/setup-lane.sh <레인>` + +## 1. 브랜치 상태 + +```text +main (4626b73, 그대로) + └─ fix/maturity-review-2026-09-25 통합 브랜치. Phase 0 + 레인 A·C·E·I·K·M 병합 완료, 게이트 통과 + └─ 4d17259 (1차 레인 통합 시점) + ├─ lane/B 완료. 레인 끝 게이트 미실행 + ├─ lane/D 완료. 레인 끝 게이트 일부만 실행(sample-removal 재실행 중 중단) + ├─ lane/F 06-10·F-8 진행 중 (wip 커밋) + ├─ lane/G F-7 진행 중 (wip 커밋) + ├─ lane/H 08-10 진행 중 (wip 커밋) + └─ lane/J 11-06·11-04 진행 중 (wip 커밋) +``` + +`wip(...)` 커밋은 멈춘 시점의 작업 중 변경이다. 그 레인을 이어서 할 때 `git reset --soft HEAD~1`로 풀고, 작업을 끝낸 뒤 정상 커밋으로 만든다. + +## 2. 레인별로 남은 일 + +| 레인 | 커밋된 작업 | 남은 작업 | +|---|---|---| +| B | 02-01~02-09, F-1 | 레인 끝 게이트(지시서 4절·6절) | +| D | 04-01~04-08 | 레인 끝 게이트(지시서 4절·6절). realtime 레시피 예산 여유가 97바이트였으니 `check:optional-recipes` 측정값 확인 | +| F | 06-01~06-09 | **06-10·F-8**(wip) → 레인 끝 게이트 | +| G | 07-02·13-10, 07-03~07-07, F-6, F-3 | **F-7**(wip) → 레인 끝 게이트 | +| H | 07-01·08-02, 08-04, 08-05·11-02, 08-07, 08-08, 08-09 | **08-10**(wip), 08-11, 08-12, 08-13, F-10 → 레인 끝 게이트 | +| J | 10-02, 10-04~10-07, 11-08 | **11-04·11-06**(wip), 11-05, 11-07, F-2, F-4, F-12 → 레인 끝 게이트 | + +후속 작업(F-x) 내용: + +- F-2: 모듈 평가 단계에서 실패한 빌드를 Playwright로 열어 `BootErrorShell`을 확인하는 spec (09-03의 남은 부분) +- F-4: 22:39에 어떤 fixture의 pnpm 실행이 공유 `node_modules/.pnpm/lock.yaml`과 `.bin`을 다시 썼다. 내용은 `pnpm-lock.yaml`과 같았다. 원인을 찾고 막는다(임시 폴더의 가짜 node_modules로 실험) +- F-7: 운영 CSP(`unsafe-eval` 없음) 아래에서 zod가 첫 schema를 만들 때 eval 가능 여부를 시험해 위반을 낸다. 모든 schema 생성 전에 `z.config({ jitless: true })`를 적용하고, `tests/e2e/production-csp.spec.ts`의 init script 없이 위반 0건(3엔진) +- F-8: `vite.service-worker.config.ts`가 production SW build에서도 `public/config.json`을 읽는다(06-10과 함께 닫음) +- F-10: 폼의 unavailable 계열 실패가 아직 ErrorSummary "입력 내용을 확인해 주세요" 제목 아래 나온다(08-01의 남은 부분) +- F-12: `tests/system/ci-runner/ci-evidence-freshness.test.ts`가 임시 root에 node_modules·lockfile이 없어 pnpm이 설치를 시작하고 `ERR_PNPM_IGNORED_BUILDS`로 실패 +- F-11(사용자 몫): SBOM이 번들에 들어가는 `scheduler@0.27.0`을 development로 분류. 의존성 기준선 재승인이 필요하다 +- F-13(마지막에): 태그 `v0.2.0`을 만들 때 `package.json` version과 `public/release-manifest.json`, `config/security/dependency-baseline.json`, 테스트 3개(`tests/component/runtime-application.test.tsx`, `tests/features/reference-feature/reference-production-vertical.test.tsx`, `reference-runtime-composition.test.ts`)를 함께 올린다. CHANGELOG의 "진행 중" 절도 정리한다 + +## 3. desktop에서 이어가는 순서 + +1. 이 브랜치와 레인 브랜치를 받는다. + ```bash + git fetch origin + git switch fix/maturity-review-2026-09-25 + for L in B D F G H J; do git branch --track lane/$L origin/lane/$L; done + corepack pnpm install --frozen-lockfile + ``` +2. 통합 브랜치에서 게이트를 한 번 돌려 기준선을 확인한다(`tasks/todo.md` "공통 검증" 명령). +3. 레인 worktree를 만든다. 레인 브랜치가 이미 있으면 그대로 checkout한다. + ```bash + tasks/lanes/setup-lane.sh F + ``` +4. 레인을 이어서 진행한다. 서브에이전트를 쓰면 `tasks/lanes/LANE-BRIEF.md`를 먼저 읽게 한다. Playwright 포트는 레인마다 다르게 쓴다(B 4275, D 4276, F 4277, G 4278, H 4279, J 4280). +5. 레인을 하나씩 통합한다(4절). +6. 통합이 끝나면 5절의 마지막 작업을 한다. + +## 4. 통합 절차 (1차 레인 때 쓴 방식) + +1. 통합 브랜치에서 `git merge --no-ff lane/`. +2. 게이트를 main 워킹트리가 아니라 분리 worktree에서 돌린다(`tasks/lanes/setup-lane.sh INT fix/maturity-review-2026-09-25`). 병렬 레인이 공유 `node_modules`를 쓰는 동안 main에서 pnpm 설치가 돌면 안 되기 때문이다. +3. 게이트: 공통 게이트 + `check:ci` + `check:adapter-inventory` + `verify:documentation` + `build` + `check:optional-recipes` + 제거 검증 4개(`test:sample-removal`, `test:optional-recipe-removal`, `test:browser-file-storage-removal`, `test:realtime-removal`). +4. 레시피 번들 예산(`config/recipes/frontend-capability-recipes.json`의 `bundleBudgetGzipBytes`)은 크기 래칫이다. 초과하면 측정값(`artifacts/quality/optional-recipes.json`)을 100바이트 단위로 올린 값으로 고치고, 늘어난 이유(발견 ID)를 커밋에 적는다. +5. `config/ci/gates.json`이 두 레인에서 충돌하면 병합한 뒤 `CI_CONTRACT_BASELINE_OWNER=… CI_CONTRACT_BASELINE_REASON=… corepack pnpm update:ci-contract-baseline` → `corepack pnpm generate:ci-workflow` → `tests/unit/ci-workflow-generation.test.ts` 개수 갱신 → `check:ci`. +6. abort 래칫(`scripts/check-adapter-inventory.ts`의 `HAND_ROLLED_ABORT_CEILING`, 현재 13)은 실측이 내려가면 같이 내린다. +7. `todo.md`에서 병합한 레인의 항목을 `[x]`로 바꾼다. + +## 5. 마지막 작업 + +- 12-12: `tsconfig.base.json`에 `noUnusedLocals` 켜고 나온 건 정리 (D-19) +- 14-07: 문서의 수치·목록 정정. 게이트 수는 레인 K 기준 27개(016 폐기, 028 추가). 레인 J가 게이트를 바꿨으면 다시 센다 +- F-13: 버전 올리기와 로컬 태그 `v0.2.0`(push는 사용자, U-3) +- 리뷰 README(`docs/reviews/2026-09-25-maturity-review/README.md`) 발견 색인의 비고를 "해결 · <커밋>"으로 갱신 +- CHANGELOG "진행 중" 절 정리 +- 최종 체크포인트: `tasks/plan.md` "Checkpoint 최종"과 새 worktree(깨끗한 체크아웃)에서의 공통 게이트 +- 사용자 몫(U-1~U-5, F-11)은 `SPEC.md` "범위 밖"과 `todo.md` 끝에 있다 + +## 6. 알아 둘 것 + +- 부하 flaky: `tests/integration/provider-guardian-transaction.test.ts`가 부하가 높을 때 시간 초과로 실패한다. 단독 실행은 통과한다. +- `test:system`의 `tests/system/ci-runner/ci-artifact-contract.test.ts`는 단독 실행에서도 10초 시간 초과가 났다(레인 C 보고). 공통 게이트 밖이다. +- 1차 레인 통합 후(4d17259) 공통 게이트, `check:ci`, `check:adapter-inventory`, `verify:documentation`, `check:registries`, `check:diagnostics`, `check:i18n`, `build`, `check:optional-recipes`, 제거 검증 4개가 모두 통과했다. 레인 M 병합(d2c197d) 뒤에는 전체 게이트를 다시 돌리지 않았다(레인 M 자체의 레인 끝 게이트는 통과). diff --git a/tasks/lanes/LANE-BRIEF.md b/tasks/lanes/LANE-BRIEF.md new file mode 100644 index 00000000..2d41d186 --- /dev/null +++ b/tasks/lanes/LANE-BRIEF.md @@ -0,0 +1,80 @@ +# 구현 레인 공통 지시서 (모든 레인 에이전트가 먼저 읽는다) + +원본 repo: 이 저장소를 clone한 경로(아래 `$REPO`) +통합 브랜치: `fix/maturity-review-2026-09-25` +너의 작업 디렉터리(worktree)와 브랜치는 프롬프트에 적혀 있다. **그 디렉터리 밖의 파일은 읽기만 한다.** 원본 repo의 워킹트리와 다른 레인 worktree는 절대 수정하지 않는다. + +## 1. 먼저 읽을 것 (worktree 안의 파일) + +1. `SPEC.md` — 공통 완료 기준, 결정 표 D-1~D-19, 범위 밖 항목 +2. `tasks/plan.md` — 레인 구조, 파일 소유 표 +3. `tasks/todo.md` — 너의 레인 섹션(작업 목록과 순서) +4. `CLAUDE.md` — repo 전제(템플릿, 배럴이 공개 경계, kernel 예외) +5. `docs/reviews/2026-09-25-maturity-review/<영역 문서>` — 네 작업 ID 항목 전부. 근거·발생 조건·최소 개선 방향·완료 기준·검증 방법이 여기 있다. + +**완료 기준의 기준은 리뷰 항목의 "완료 기준" 칸이다.** SPEC 결정 표가 다르게 정했으면 결정 표를 따른다. + +## 2. 작업 하나의 순서 + +todo 순서대로 하나씩 한다. + +1. 리뷰 항목과 관련 코드를 읽는다. 근거 줄 번호는 리뷰 당시(`4626b73`) 기준이다. 코드가 바뀌었을 수 있으니 직접 확인한다. +2. **RED:** 문제를 재현하는 테스트를 먼저 쓰고, 실패하는 것을 확인한다. 문서만 바꾸는 작업은 이 단계가 없다. 변이 생존이 문제였던 작업은 리뷰에 적힌 변이를 넣었을 때 새 테스트가 실패하는지도 확인한다. +3. **GREEN:** 가장 작은 변경으로 통과시킨다. 주변 코드를 정리하지 않는다. 필요 없는 추상화를 만들지 않는다. +4. **게이트:** 아래를 모두 통과시킨다. + ``` + corepack pnpm check:architecture && corepack pnpm check:types && corepack pnpm lint && corepack pnpm test:unit && corepack pnpm test:component && corepack pnpm test:integration && corepack pnpm test:contract && corepack pnpm test:runtime-schema + ``` + adapter 파일을 추가·이동했으면 `docs/reviews/adapters/INVENTORY.md`를 고치고 `corepack pnpm check:adapter-inventory`도 돌린다. +5. **커밋:** 그 작업이 바꾼 파일만 `git add <경로>`로 스테이징한다(`git add -A` 금지). 메시지 형식은 기존 이력과 같다. + ``` + fix(): <무엇을 고쳤나, 영어 소문자 시작> (<발견 ID>) + + <왜, 1~3줄> + + Co-Authored-By: Claude Opus 5.5 + ``` + 종류는 `fix`, `test`, `docs`, `perf`, `refactor`, `build`, `ci` 중 맞는 것을 쓴다. +6. `tasks/todo.md`는 **고치지 않는다.** 체크는 오케스트레이터가 통합 때 한다. + +## 3. 규칙 + +- **파일 소유:** `tasks/plan.md` 표에서 다른 레인이 소유한 파일은 바꾸지 않는다. 꼭 바꿔야 하면 바꾸지 말고 보고에 "다른 레인 요청"으로 적는다. `config/ci/gates.json`과 `.gitea/workflows/quality-gates.yml`은 레인 Z(Phase 0)와 K만 바꾼다. +- **범위:** 결정 표 밖의 설계 판단이 필요하면(공개 포트를 깨야 함, 리뷰 방향이 코드와 맞지 않음 등) 그 작업은 멈추고 "막힘"으로 보고한다. 그다음 독립적인 작업은 계속한다. +- **무관한 테스트 실패:** 다른 레인이 병렬로 돌아 호스트 부하가 높다. 네 변경과 무관해 보이는 실패가 나면 그 파일만 단독으로 다시 돌린다. 단독으로 통과하면 "부하 flaky"로 보고에 적고 진행한다. 단독으로도 실패하면 원인을 찾는다. +- **실행:** `corepack pnpm