코칭 엔진 v2 강화 — 하이브리드 개발 원자단위 WBS (빌드 플랜)

✅A-01 · GROUP_INGREDIENTS 빈도 정비(I) — 실측 급식빈도 반영·단호박 강등코드 코드 · 0.5h

• coachRecos.ts GROUP_INGREDIENTS의 '비타민A채소' 배열을 ['당근','시금치','근대','단호박']로 재정렬(당근184>시금치13>근대11>단호박0)
• '기타채소'는 토마토42>브로콜리25>양배추20 순 정렬, 단 기존 ['브로콜리','양배추','애호박','버섯','토마토'] 유지가 Letter A 회전에 영향 — Letter A는 대조군이므로 GROUP_INGREDIENTS는 상수 정렬 변경이 pickFoodReco(seed%length 회전) 결과를 바꾼다. 따라서 신규 상수 GROUP_INGREDIENTS_RANKED를 coachMaterials.ts에 별도로 두고 빈도 메타({nm,gioFreq,gioPct}) 부착, 기존 GROUP_INGREDIENTS는 무변경(Letter A 보존)
• coachMaterials.ts에 const GIO_FREQ: Record<string,{freq:number;pct:number}> 신설 — 당근{184,2}·토마토{42,12}·브로콜리{25,18}·양배추{20,24}·시금치{13,33}·근대{11,39}·단호박{0,100}·치즈{18,27}·요거트{0,100} (인계서 실측표)
• GROUP_INGREDIENTS_RANKED는 GROUP_INGREDIENTS 키별로 GIO_FREQ.freq 내림차순 정렬한 사본(빈도 미상 식재료는 freq=0 취급해 끝으로)
• 순수 함수 ingredientGioFreq(nm:string):{freq:number;pct:number} export — 미상이면 {freq:0,pct:100}

• 랭킹 엔진(A-04)이 '비타민A채소' 결핍 시 단호박(0회) 대신 당근(184회)을 상위로 올린다
• Letter A의 pickFoodReco 회전 결과가 이 변경으로 바뀌지 않는다(GROUP_INGREDIENTS 원본 불변)

• GROUP_INGREDIENTS_RANKED·GIO_FREQ·ingredientGioFreq export됨
• Letter A 경로(GROUP_INGREDIENTS 원본) 무변경 회귀 테스트 통과
• npm test 그린(prebuild 게이트)
• 순수 함수(fs/HTTP 불사용)

✅A-02 · liked 판정(D) — 집≠급식·2일+·거부없음 deriveLikedIngredients코드 코드 · 1h

• coachMaterials.ts deriveLikedIngredients(meals: {food:string; place:string|null; ateWell:boolean|null; refused?:boolean; daysAgo:number}[]): {liked:string[]; refused:string[]}
• liked 조건: place가 'daycare'가 아닌(집 또는 null=집통제) 끼니에서 ateWell!==false 로 등장한 서로 다른 날(daysAgo 기준 distinct) 수 ≥ 2
• route.ts 290줄 패턴 차용 — place==='daycare'면 집 아님. 'snack'(간식)도 '차려진 것'이라 liked 가산 제외(인계서 D: 급식/간식은 차려진 것=선호 신호 아님)
• refused: refused===true 또는 ateWell===false 로 등장한 식재료 집합. liked와 refused 동시 해당 시 refused 우선(liked에서 제거)
• day distinct 계산은 daysAgo 값으로 그룹핑(같은 daysAgo=같은 날). 동일 식재료가 같은 날 2끼면 1일로 카운트
• 빈 입력·전부 daycare면 liked=[] 반환(온보딩 케이스는 A-09에서 별도 처리)

• 아린이 집에서 당근을 3일(서로 다른 날) 잘 먹음 → liked에 '당근' 포함
• 급식에서만 시금치 등장(집 기록 0) → liked 제외(차려진 것)
• 집에서 가지 먹였으나 ateWell=false 1회 → refused, liked 아님

• deriveLikedIngredients export·순수 함수
• route.ts place/ateWell/refused 데이터 모양과 일치(필드명 검증)
• fixture로 엣지 박제(급식만·거부충돌·같은날2끼)
• npm test 그린

✅A-03 · 괴식 조합 검증(A) — comboMatrix.scoreCombo (kit-dish-matrix + pair)코드 코드 · 1h

• comboMatrix.ts scoreCombo(dish:string, ing:string): {score:number; source:'matrix'|'cells'|'pair'|'none'} — kitGuide.ts와 동일 데이터(kit-dish-matrix.json) 직접 로드 또는 kitGuide 확장
• scores[dish]?.[ing]가 있으면 그 값(0~3)·source='matrix'. 미역국·당근=1 검증
• matrix에 dish 행 자체가 없으면 food-graph pair strength로 폴백: neighborsOf(ing) 중 kind==='pair' && nm===dish 의 strength(0~3)·source='pair'
• 어느 데이터에도 없으면 {score:0, source:'none'}
• isComboOk(dish,ing,threshold=2):boolean = scoreCombo().score >= threshold
• matrix 점수 분포는 1/2/3만 존재(0 없음·실측 확인) → threshold=2면 score=1(미역국+당근)은 탈락, score=2,3 통과

• 볶음밥+당근(=3) → isComboOk true
• 미역국+당근(=1) → isComboOk false(괴식 차단)
• 카레+당근(=3)·덮밥+당근(=3) → OK
• matrix에 없는 음식+식재료 → pair 폴백 또는 none

• scoreCombo·isComboOk export·순수 함수
• 미역국+당근=1 차단 회귀 테스트 박제(인계서 6/8 괴식 교훈)
• kit-dish-matrix.json 실측 점수와 일치
• npm test 그린

✅A-04 · 4기준 가중 랭킹(C) — rankIngredients (시급도·빈도%·궁합·사촌)코드 코드 · 1.5h

• coachMaterials.ts rankIngredients(args:{targetGroup:string; groupLevel:'green'|'yellow'|'red'; liked:string[]; freqMap?:FreqMap}): {ing:string; score:number; parts:{urgency:number; freq:number; pair:number; bridge:number}}[]
• ①urgency: groupLevel red=3·yellow=1·green=0 (그룹 단위 동일 가산이지만 식품군 결핍 시급도 반영)
• ②freq: ingredientGioFreq(ing).pct를 상위%→점수 변환(pct<=5→3, <=20→2, <=40→1, else 0). 당근(2%)=3·근대(39%)=1·단호박(100%)=0
• ③pair: neighborsOf(ing) 중 kind==='pair' && liked 포함 개수(최대 2로 클램프)
• ④bridge: liked 식재료의 사촌(bridge)이 ing이면 +2(푸드체이닝 강신호)
• weighted score = urgency*1 + freq*2 + pair*1.5 + bridge*1.5 (가중치는 상수 W로 추출·테스트 가능)
• 동점 시 ingredientGioFreq.freq 내림차순 → 식재료명 사전순(결정론)
• 단호박(freq 0)은 liked 사촌/궁합 없으면 최하위로 가라앉음(인계서 I 의도)

• 비타민A채소 red·liked=['밥','달걀'] → 당근(빈도3·궁합 달걀pair) 1위, 단호박 최하위
• liked에 고구마 있으면 단호박이 bridge(고구마-단호박)로 점수 상승(푸드체이닝)
• freqMap 주입 시 popularDishes 빈도와 일관

• rankIngredients export·순수 함수·결정론
• 4기준 모두 parts에 분해되어 검증 가능
• 가중치 상수 W export(튜닝·테스트 가능)
• seed 블라인드 회전(pickFoodReco) 미사용 회귀 박제
• npm test 그린

✅A-05 · 3일 무재사용 회전(B) — rotateRecommendation (재료 결정론)코드 코드 · 1h

• coachMaterials.ts rotateRecommendation(args:{ranked:{ing:string;score:number}[]; recentRecos:string[]; cooldownDays?:number}): string|null
• recentRecos = 최근 cooldownDays(기본 3)일에 추천한 식재료 배열(coach_letters.context.altLetter.materials.recommendedIng를 route가 수집)
• 후보 = ranked.filter(r => !recentRecos.includes(r.ing)) 중 score 최댓값(랭킹 순서 보존)
• 후보가 비면(랭킹 전부 쿨다운) → ranked[0].ing 폴백(연속 결핍 대응·null 아님)
• 결정론: 동일 입력 동일 출력. 회전은 '날짜 시드'가 아니라 '이력 배제'로 달성(인계서 B '3일내 재사용 금지')
• ranked 빈 배열 → null

• 어제 당근 추천 → 오늘 ranked 당근 1위지만 recentRecos에 당근 → 치즈/시금치 선택
• 3일 전부 당근·시금치·근대 추천 → 4일째 다시 당근(쿨다운 만료)
• 결핍군에 식재료 4개뿐이고 3개 쿨다운 → 남은 1개

• rotateRecommendation export·순수 함수·결정론
• 2일 연속 다른 재료 수렴방지 회귀 박제
• 전부 쿨다운 시 폴백(null 금지)
• npm test 그린

✅A-06 · 결핍 기간 수치화(F) — deficiencyWindow (모호어 금지)코드 코드 · 0.75h

• coachMaterials.ts deficiencyWindow(signals: GroupSignal[], windowDays=7): {group:string; daysOf7:number; threshold:number; level:string} | null
• GroupSignal = {group,level,weeklyEst} (nutrition.ts 실재 타입). weeklyEst는 이미 7일 환산값(nutrition.ts 210줄 *7 계산) → daysOf7 = Math.round(weeklyEst)
• 가장 시급한 결핍 = level red 우선 → weeklyEst 낮은 순(MEAL_GROUPS 우선·과일/유제품 간식채널 제외 가능, weeklyExposureTarget 정렬 차용)
• threshold = GROUP_TARGET[group].green (곡물·채소 5, 콩류 2 등 nutrition.ts 상수) — 'N일 중 M일 필요' 사실 제공
• 전부 green이면 null(결핍 없음 — LLM에 결핍 수치 주지 않음)
• 순수 함수 — signals 외 의존 없음

• 비타민A채소 weeklyEst 2.1·red → {group:'비타민A채소', daysOf7:2, threshold:5}, LLM이 '최근 7일 중 2일'로 서술
• 전부 green → null → LLM이 결핍 언급 안 함(환각 방지)

• deficiencyWindow export·순수 함수
• threshold가 nutrition.ts GROUP_TARGET과 일치(import 또는 재정의 일관)
• green 전부면 null(환각 방지) 박제
• npm test 그린

✅A-07 · 검증 조합 후보 생성(A+D) — buildValidatedCombos코드 코드 · 1h

• coachMaterials.ts buildValidatedCombos(args:{recommendedIng:string; likedDishes:string[]; likedIngredients:string[]; threshold?:number}): {liked:string; deficient:string; score:number; source:string}[]
• likedDishes(favoriteFoods top·route.ts favMenu) × recommendedIng → scoreCombo(dish, ing) → isComboOk면 채택
• 추천 식재료가 staple(STAPLE_FORMS)이면 stapleDisplay로 형태 변환 후 조합(밥·빵·면)
• 결과는 score 내림차순·중복(liked,deficient) 제거. 최대 N개(기본 4)
• 빈 결과 가능(검증 통과 조합 0) → [] 반환(LLM에 빈 후보=조합 강요 안 함, B-G에서 폴백 처리)
• 미역국이 likedDishes에 있고 recommendedIng=당근 → 제외(score 1<2)

• likedDishes=['볶음밥','미역국'], recommendedIng='당근' → [{볶음밥,당근,3}] (미역국 제외)
• likedDishes=['카레','덮밥'], recommendedIng='당근' → 둘 다 score3 채택
• 검증 통과 0개 → 빈 배열(B가 '곁들이기' 대신 단독 노출로 폴백)

• buildValidatedCombos export·순수 함수
• 미역국+당근 제외 회귀 박제(괴식 0)
• 모든 결과 score>=threshold 보장
• 빈 후보 허용(조합 강요 금지)
• npm test 그린

✅A-08 · 근거문구 생성(C) — buildReasonPhrases코드 코드 · 0.75h

• coachMaterials.ts buildReasonPhrases(args:{ing:string; parts:{urgency:number;freq:number;pair:number;bridge:number}; window:{group:string;daysOf7:number;threshold:number}|null; pairLiked?:string; cousinOf?:string}): string[]
• freq 문구: ingredientGioFreq(ing) → '${ing}은 급식에 자주 나와요(상위 ${pct}%)' (pct<=20일 때만)
• 결핍 문구: window 있으면 '${group}가 최근 7일 중 ${daysOf7}일(권장 ${threshold}일)'
• 궁합 문구: pairLiked 있으면 '잘 먹는 ${pairLiked}에 곁들이면 자연스러워요'
• 사촌 문구: cousinOf 있으면 '${cousinOf}을 잘 먹으니 닮은 ${ing}도 도전해볼 만해요'
• 영양역할: 식재료별 NUTRI_ROLE 테이블(당근→'베타카로틴이 눈·면역', 치즈→'칼슘·단백질', 시금치→'철·엽산') — 도감 nutrition.ts nutrientsOf로 보강 가능하나 짧은 라벨은 상수 테이블
• 결과는 모호 기간어 없는 수치 문구만(F 연계). LLM은 이 문구를 '재료'로 받아 자기 문장으로 풀어씀

• 당근 추천 → ['당근은 급식에 자주 나와요(상위 2%)','베타카로틴이 눈·면역에 좋아요','비타민A 채소가 최근 7일 중 2일(권장 5일)']
• 치즈+pairLiked=빵 → ['잘 먹는 빵에 곁들이면 자연스러워요','칼슘·단백질이 풍부해요']

• buildReasonPhrases export·순수 함수
• NUTRI_ROLE 라벨 테이블(핵심 식재료 커버)
• 모호 기간어 미포함·수치 문구만
• npm test 그린

✅A-09 · 온보딩 가드(E) — 기록<3일 분기 materialsForLowData코드 코드 · 0.5h

• coachMaterials.ts materialsForLowData(args:{recordedDays:number; hasHeight:boolean; hasWeight:boolean; hasConditions:boolean; mealCount:number; tipSeed:number}): {mode:'onboarding'; missingInputs:string[]; tip:string} | {mode:'analyze'}
• recordedDays<3 → mode:'onboarding'. computeSignals도 recordedDays<3이면 level yellow 보류(nutrition.ts 282줄)와 일관
• missingInputs: hasHeight false→'키', hasWeight false→'몸무게', hasConditions undefined→'알레르기·만성질환', mealCount<3→'끼니 기록' (안내 항목)
• tip: coach-tips.json 또는 상수 풀에서 tipSeed로 결정론 선택(배경 없는 즉효 편식 팁 — 데이터 무관)
• recordedDays>=3 → {mode:'analyze'} (selectDailyMaterials가 정상 분석 진행)
• 순수 함수

• 가입 다음날(기록 1일) → onboarding, missingInputs=['키','몸무게'], tip='새 음식은 접시 한쪽에 작게 올려두기만 해도 익숙해져요'
• 기록 5일·키몸무게 있음 → analyze 모드

• materialsForLowData export·순수 함수
• 온보딩 모드에 결핍 분석 미포함(환각 차단) 박제
• 3일 임계가 nutrition.ts와 일관
• npm test 그린

✅A-10 · 오케스트레이터 — selectDailyMaterials(args) 통합코드 코드 · 1h

• coachMaterials.ts selectDailyMaterials(args:{signals:GroupSignal[]; meals:MealRow[]; favoriteFoods:string[]; recentRecos:string[]; freqMap?:FreqMap; recordedDays:number; onboardingMeta:{...}; tipSeed:number}): DailyMaterials
• DailyMaterials = {mode:'onboarding'|'analyze'; targetGroup:string|null; recommendedIng:string|null; validatedCombos:{liked,deficient,score,source}[]; reasonPhrases:string[]; deficiencyWindow:{group,daysOf7,threshold}|null; liked:string[]; refused:string[]; missingInputs?:string[]; tip?:string}
• 흐름: ①materialsForLowData → onboarding이면 즉시 반환 ②deficiencyWindow(signals)→targetGroup ③deriveLikedIngredients(meals)→liked/refused ④rankIngredients(targetGroup,liked,freqMap) ⑤rotateRecommendation(ranked,recentRecos)→recommendedIng ⑥buildValidatedCombos(recommendedIng,favoriteFoods,liked) ⑦buildReasonPhrases
• targetGroup null(전부 green)이면 recommendedIng=null·combos=[]·reasonPhrases는 유지 칭찬용 빈/긍정 사실(결핍 강요 안 함)
• 결정론: 동일 입력 동일 출력. seed 없음(회전은 recentRecos 이력으로). 순수(fs/HTTP 불사용, freqMap은 주입)
• 이 함수는 Letter B 전용 — Letter A(planFor/composeLetter)는 호출하지 않음(대조군 보존)

• 아린 5일 기록·비타민A채소 red·liked=['밥','달걀']·어제 당근 추천 → {targetGroup:비타민A채소, recommendedIng:시금치(당근 쿨다운), validatedCombos:[볶음밥+시금치...], reasonPhrases:[...], deficiencyWindow:{...}}
• 가입 다음날 → mode:onboarding·missingInputs·tip
• 전부 green → targetGroup null·결핍 강요 없음

• selectDailyMaterials export·DailyMaterials 타입 export·결정론·순수
• A-02~A-09 전부 조립·각 분기 통합 테스트
• Letter A 경로 미참조(대조군 보존) 박제
• npm test 그린(prebuild 게이트)

✅A-11 · freqMap 실배선 — loadFreqMap·route 전달 헬퍼(C 죽은 코드 부활)코드 코드 · 0.75h

• coachMaterials.ts normalizeFreqMap(raw: unknown): FreqMap — route.ts가 로드한 ingredient-recipes JSON을 FreqMap으로 안전 변환(키=식재료, 값=[{name,freq}] freq 내림차순)
• route.ts 현재 freqMap 로드 위치(미배선) 확인 후, selectDailyMaterials args.freqMap로 넘기는 어댑터 시그니처 고정(실제 cron 배선은 H 에픽 의존)
• freqMap 미주입/빈 객체여도 popularDishesFor가 kit-matrix(dishesForIngredient)로 폴백함을 회귀 테스트로 고정(coachRecos.ts 45줄 폴백 경로)
• raw가 null/형식불량이면 {} 반환(graceful)
• freq<4 항목은 popularDishesFor에서 이미 제외(coachRecos.ts 44줄 r.freq>=4) — normalize는 원본 보존, 필터는 소비측

• route.ts가 ingredient-recipes.json 로드 → normalizeFreqMap → selectDailyMaterials(freqMap)로 빈도 가중 활성화
• freqMap 로드 실패 → {} → kit-matrix 폴백으로 추천 계속(죽지 않음)

• normalizeFreqMap export·순수·graceful
• freqMap 빈객체 시 kit-matrix 폴백 회귀 박제(죽은코드 방지)
• 실제 cron 배선은 H 에픽 의존으로 명시(depends_on에 외부 표기)
• npm test 그린

✅A-12 · 재료 fixture + 회귀 박제 (아린 6통 괴식·수렴 사례)테스트 테스트 · 1h

• tests/fixtures/materials.ts — 아린 모양: 비타민A채소 red·liked=['밥','달걀','미역국']·favoriteFoods=['볶음밥','미역국','김밥'] 등 6일치
• tests/coach-materials.test.ts에 6일 루프 시뮬: 각 날 recentRecos를 직전 3일 추천으로 갱신하며 selectDailyMaterials 호출
• 검증①: 6일 validatedCombos 전 항목 score>=2 (미역국+당근 같은 괴식 0)
• 검증②: 6일 recommendedIng 시퀀스에서 연속 3일 중 동일 식재료 재사용 0 (수렴 방지)
• 검증③: red 입력일은 deficiencyWindow 비-null·daysOf7 수치 존재
• 검증④: 온보딩(1~2일) fixture는 mode:'onboarding'
• 엣지 발견 시 fixture 추가 + red→green 사이클(불변 원칙③ 복리)

• 인계서 6통 수렴 사례 입력 → 6일 추천이 당근→시금치→근대... 로 회전(동일 식재료 연속 3일 0)
• 미역국 favorite여도 6일 내 미역국+당근 조합 0건

• fixtures/materials.ts·coach-materials.test.ts 추가
• 인계서 6통 괴식·수렴 사례 회귀 박제(red→green)
• 6일 시뮬 괴식 0·연속3일 무재사용 검증
• npm test 그린(prebuild 게이트)

✅B-01 · TeachingGuide 타입·계약 정의 (coachGuide.ts 골격)설계 코드 · 0.5h

• 신규 파일 lib/coachGuide.ts 생성. import: UNITS·type UnitId·type UnitDef from './curriculumUnits', type DailyDecision from './curriculum', type WeeklyAnchor·WeeklyArcStage from './coachWeekly'.
• export type TeachingGuide = { unit_ko: string; lever: UnitDef['lever']; stepBehavior: string; why: string; arcStage: WeeklyArcStage; weeklyImpressionSoft: string | null; doNotRestate: string[]; stepN: number; mode: DailyDecision['mode'] }
• arcStage 타입은 coachWeekly.ts의 WeeklyArcStage(intro|how|obstacle|observe|reinforce)를 재사용(LetterInput.weeklyArc.stage의 'why'=intro 취급은 조립단에서 흡수).
• JSDoc: '결정·진단=결정론(이 함수). 문장·도입·톤=LLM. 고정 블록/byte 거울 금지 — guide는 LLM에 주는 *가이드*이지 출력 문장이 아니다.' 명시.
• 파일 헤더에 'EPIC B · Letter B 전용 · A(planFor+composeLetter)는 이 모듈을 import하지 않는다' 주석.

• 크론(EPIC 외부 H)이 decideDailyV3 결과 + 주간 닻을 buildTeachingGuide에 넣어 TeachingGuide를 받고, coachRecos 재료와 합쳐 LetterInput을 만든다.
• 리플레이/테스트가 TeachingGuide 형태를 단독 검증.

• lib/coachGuide.ts 컴파일(tsc 0)
• TeachingGuide 9필드 export
• npm test 그린(prebuild 게이트)
• A 경로(coach.ts) 무변경 — coachGuide는 별도 모듈

✅B-02 · decideDailyV3 결정 → stepBehavior·unit_ko·lever·stepN 매핑코드 코드 · 1h

• buildTeachingGuide(p: {decision: DailyDecision | null; anchor: WeeklyAnchor | null; unitDef?: UnitDef}) 시그니처. decision.unit으로 UNITS[decision.unit] 조회(unitDef 인자는 테스트 주입용 옵션).
• unit_ko = UNITS[unit].label (예 'table-stage'→'식탁 무대', 'exposure-savings'→'새 음식 조금씩 노출').
• lever = UNITS[unit].lever.
• stepN = clamp(decision.step, 1, def.steps.length); stepBehavior = def.steps[stepN-1].behavior (예 table-stage step1='하루 한 끼 화면 끄고 식탁에서').
• decision.step이 0이거나 def.steps.length 초과 시 Math.max(1, Math.min(step, len))로 클램프(curriculum.ts evolveRow가 step 0~len 다룸 — 방어).
• mode = decision.mode 그대로 통과(advance/deepen/pivot/maintain/celebrate/observe).

• focus=table-stage·step=2·mode=advance → unit_ko='식탁 무대'·lever='environment'·stepBehavior='주 5끼+ 같은 자리·같은 시간'·stepN=2.
• pivot 결정(decision.unit=pivotTo) → 새 유닛의 label/behavior로 정확히 전환(stop된 유닛 아님).

• 12유닛×2단계 매핑 전부 검증
• step 경계 클램프 테스트 그린
• 순수함수(DB·LLM·시계 0)·단독 테스트 가능
• npm test 그린(prebuild 게이트)

✅B-03 · mode → arcStage 결정론 매핑 (advance/deepen/pivot/celebrate/observe→intro/how/obstacle/observe/reinforce)코드 코드 · 1h

• arcStage 결정 우선순위: ① mode='celebrate' → 'reinforce'(졸업 축하=실행 인정 톤) ② firstOfWeek && (mode='advance'||'pivot') → 'intro'(새 유닛/단 도입 — coachDaily.introNeededV3와 정합) ③ mode='maintain' → 'observe'(정체 위안·행동 0) ④ progress관측 && lastArcStage!=='reinforce' → 'reinforce' ⑤ 폴백 = planFromWeekly의 ROT=['how','obstacle','observe'] 요일 회전 재사용.
• planFromWeekly(coachWeekly.ts:297-300)의 stage 결정 로직과 동일 규약 — reinforce 이틀 연속 금지(lastArcStage==='reinforce'면 ROT로 환기) 보존.
• arcStage 매핑 함수는 순수: arcStageFor(p: {mode; firstOfWeek; lastArcStage; progress; dow}): WeeklyArcStage 로 분리해 단독 테스트.
• mode='deepen'은 firstOfWeek 아니면 ROT 회전(같은 유닛 심화=새 도입 아님 → intro 금지).

• 주 첫 편지·focus 새 유닛 advance → intro(왜 이 코칭 1회).
• mode=maintain(정체) → observe 톤(행동 권유 0·태도 위안).
• 졸업(celebrate) → reinforce(실행 인정).
• 어제 reinforce였는데 오늘도 progress → ROT 단계로 환기(reinforce 2연속 차단).

• arcStageFor 순수함수 분리·단독 테스트
• planFromWeekly 아크 규약(reinforce 2연속 금지·intro 주1회) 정합 확인
• 11 케이스 그린
• npm test 그린

✅B-04 · why(코칭 근거) 결정론 생성 — 유닛·단계·수치 기반코드 코드 · 1h

• why는 유닛 lever별 근거 템플릿 재료(문장 아닌 '사실 조각'): 예 table-stage → evidence.envTablePct7d 값 + TH.envTableStep1 임계 → '식탁 식사 비율 {pct}%(목표 {step1*100}%)'. exposure-savings → evidence.targetExposeDays7d + TH.exposeWeekly.
• 수치는 evidence(curriculum.ts evolveRow가 적립한 ProgressRow.evidence)에서 읽음 — null이면 '아직 표본 부족'으로 degrade(환각 금지).
• mode별 why 각도: advance='단을 올릴 신호 충족' / deepen='신호는 있으나 사다리 정체' / maintain='정체 — 행동보다 태도 인정' / pivot='이 축이 안 먹혀 목표 전환' / celebrate='유지 주 통과'.
• why는 1~2 사실 조각의 배열을 합친 짧은 문장(LLM이 그대로 베끼지 않고 '재료'로 씀). 슬롯값 byte 노출 금지 — 수치는 넣되 정형 문장 금지.
• 임계 수치는 TH(curriculumUnits.ts:51)에서만 읽음(매직넘버 금지).

• table-stage advance, envTablePct7d=0.45 → why='식탁 식사 45%로 1차 목표(40%) 넘어 한 단계 올릴 때'.
• exposure-savings, targetExposeDays7d=1, 임계 2 → why='이번 주 노출 1일(주 2회 목표 미달)'.
• evidence 없음(표본 부족) → why='아직 판단할 표본이 부족 — 관찰 주'.

• 수치 근거 evidence/TH 연동
• 모호어 0건 회귀 테스트
• null evidence degrade(환각 0)
• 순수함수·단독 테스트·npm test 그린

✅B-05 · weeklyImpressionSoft — runWeeklyPlanning impression의 부모비노출 가공코드 코드 · 0.5h

• anchor.impression(WeeklyAnchor.impression: string|null)을 입력. null이면 weeklyImpressionSoft=null.
• 내부 금칙어 스캔(SYSTEM_WEEKLY·SYSTEM_RECAP 규칙과 동일 철학): '미션'·'과제'·'진도'·'단계'·'점수'·'등급'·진단어(ARFID·신공포 등) 포함 시 해당 문장 드롭.
• 길이 상한 200자 슬라이스(impression은 600자까지 가능).
• weeklyImpressionSoft는 LLM에 '배경 참고(직접 인용 금지)' 재료로 전달됨을 JSDoc 명시 — buildRecapUser(coachWeekly.ts:373)의 '직접 인용 금지' 규약 차용.

• impression='지난주 환경 개선됐고 이번 주는 식품 노출로' → soft='지난주 환경이 나아졌고 이번 주는 새 음식 노출 쪽' (내부어 없음).
• impression에 'ARFID 의심' 포함 → 해당 문장 드롭(부모 비노출).
• impression=null → null.

• 내부어/진단어 스캔·드롭
• 길이 상한
• anchor/impression null 방어
• 순수함수·npm test 그린

✅B-06 · doNotRestate — D-04 사실 재서술 금지 목록 산출코드 코드 · 1h

• 입력: recentCtxs(최근 7일 coach_letters.context.altLetter들의 design/mirror/why 메타) + recentIntroUnitsOf(coachDaily.ts:51) 재사용해 이미 intro한 유닛 id 수집.
• doNotRestate 항목 예: '이미 도입한 유닛(unit_ko) 재도입 금지', '직전 편지가 인용한 거울 사실 재인용 금지', 직전 도입 문장 첫 25자(coach.ts varyOpener 철학) 등.
• coachDaily.recentIntroUnitsOf를 import해 재사용(중복 구현 금지 — blocks의 'unit.intro.N' 패턴 파싱).
• 현재 focus 유닛이 recentIntroUnits에 있으면 doNotRestate에 'intro 재도입 금지' 추가(introNeededV3와 정합).
• 순수함수: doNotRestateFrom(ctxs, focusUnitKo): string[] 분리.
• 빈 ctxs/누락 필드 방어 → [].

• 최근 7일 중 어제·그제 편지가 table-stage intro → doNotRestate=['식탁 무대 도입 다시 쓰지 마세요'].
• 직전 편지 mirror가 '당근 3일 등장' 인용 → doNotRestate에 그 사실 재인용 금지.
• 신규 자녀(ctxs 빈) → doNotRestate=[].

• coachDaily.recentIntroUnitsOf 재사용(중복구현 0)
• 빈/오염 입력 방어 []
• 순수함수·단독 테스트
• npm test 그린

✅B-07 · 온보딩·무기록 분기 (decision=null / lowData=true)코드 코드 · 1h

• 입력에 lowData: boolean 추가(decideDailyV3 결과의 lowData·decision 사용).
• lowData||!decision → TeachingGuide: { unit_ko: focus?.label || '관찰', lever: focus?.lever || 'mixed', stepBehavior: '', why: '기록이 3일 미만이라 패턴 단정 대신 관찰 중', arcStage: 'observe', doNotRestate: ['아직 없는 식품군 결핍·패턴 단정 금지(환각)'], stepN: max(1,frow.step), mode: decision?.mode||'observe' }.
• decideDailyV3(coachDaily.ts:100-106)의 lowData 반환과 정합 — byDay<TH.minLoggedDays(3) 분기.
• 온보딩 가이드는 수치 why(B-04) 경로를 타지 않음(가짜 수치 0).

• 가입 다음날(기록 1일) → lowData=true → why에 결핍 수치 없음·'관찰 중'.
• decision=null(focus 없음) → 관찰 가이드, doNotRestate에 단정 금지.

• lowData/decision=null 분기 분리
• 가짜 수치/결핍 0 회귀
• decideDailyV3 lowData 정합
• 순수함수·npm test 그린

✅B-08 · buildTeachingGuide 통합 — 전 조각 합성 + 진입점 시그니처코드 코드 · 1.5h

• 진입 시그니처에 DailyV3Result(coachDaily.ts:91) 전체를 받아 lowData·decision·plateau를 분기.
• 조립 순서: ① lowData||!decision → onboardingGuide(B-07) 즉시 반환 ② else { unit_ko/lever/stepBehavior/stepN/mode=B-02, arcStage=arcStageFor(B-03), why=whyFor(B-04), weeklyImpressionSoft=B-05, doNotRestate=doNotRestateFrom(B-06) }.
• plateau(decideDailyV3 plateau=true) → arcStage 'observe' 강제(행동 0·위안), why=B-04 maintain 각도.
• anchor=null(닻 없음) → mission_target/impression 의존 필드는 null/폴백(안전 제1원칙 — coachWeekly throw 안 함과 정합).
• 반환은 순수(LLM 0콜) — 'guide 합성=결정론, 작문=LLM' 한 줄 보장.
• JSDoc에 'Letter B 전용. A는 planFor+composeLetter 무변경' 재명시.

• 크론이 decideDailyV3 → buildTeachingGuide → coachRecos 재료 합본 → LetterInput(Letter B) → composeLetter(B 변형).
• plateau 주 → observe 가이드(채근 0).
• 닻 없는 신규 자녀 → 폴백 가이드(throw 없음).

• B-02~B-07 위임·통합
• LLM 0콜 회귀 테스트
• 결정론(동일입력=동일출력) property 테스트
• anchor=null 안전
• npm test 그린(prebuild 게이트)

✅B-09 · 진도 영속 정책(B는 진도 굴림) — goalsAfter/updates 반영 계약설계 코드 · 1h

• coachGuide.ts JSDoc + 별도 export const GUIDE_PERSISTENCE_NOTE(문자열 상수)에 정책 박제: 'Letter B만 decideDailyV3.updates를 curriculum_progress에, goalsAfter를 weekly_plans.goals(닻)에 upsert한다. A(planFor)는 진도 비참여.'
• 피벗 영속 정합: advanceProgress(curriculum.ts:212)가 goalsAfter로 focus 플립을 반환 — 크론이 닻에 저장해야 다음날 피벗이 안 되돌려짐(B-26 리플레이 교훈)을 명시.
• compare 모드(아린)는 v3 순수 블록 조립 안 함 — 기존 v3Enabled 경로 대신 compare 경로가 진도 굴림을 인수함을 명시(인계서 '아린은 더이상 v3 블록 조립 안 함').
• 검증 헬퍼 export: nextProgressState(prev, dailyResult): {progressUpserts: ProgressRow[]; goalsForAnchor: Goal[]} — 순수 함수로 '무엇을 저장할지'를 계산(SQL 실행은 H, 단 형태는 여기서 테스트).

• B 편지 발행 후 크론이 nextProgressState로 저장할 진도 행·goals 산출 → DB upsert(H).
• pivot 발생 → goalsForAnchor에 focus 플립 반영 → 다음날 연속.
• A는 nextProgressState 미호출(진도 비참여).

• nextProgressState 순수함수·진도 형태 계산
• 피벗 영속 계약 테스트
• A 비참여 명문화
• SQL 실행은 H에 위임(여기선 형태만·SQL 실행확인 없이 다음단계 금지 원칙은 H가 준수)
• npm test 그린

✅B-10 · 데이터 정합성 I — GROUP_INGREDIENTS 대표 식재료 급식빈도 정비(가이드 노출 정합)코드 코드 · 1h

• ★재료 선택은 결정론(코드 회전·EPIC C)이고 B 가이드는 unit/stepBehavior/why만 못 박는 경계 확인 — B는 식재료 이름을 새로 만들지 않는다(괴식·환각 차단).
• curriculumUnits.ts의 food 유닛 extract는 foodTarget(외부 주입)을 받음(exposure-savings:182) — 대표 식재료 자체를 가진 GROUP_INGREDIENTS는 coachRecos.ts 소관이므로, B 원자는 '가이드가 빈도 0 식재료를 why/stepBehavior에 하드코딩하지 않음'을 보장하는 가드만 추가.
• 실측 급식빈도 fixture(인계서 제공: 당근184·토마토42·브로콜리25·양배추20·시금치13·근대11·단호박0·치즈18·요거트0)를 tests/fixtures에 박제.
• 가드: assertNoZeroFreqStaple(guide, freqMap) — 가이드의 why/stepBehavior에 freqMap[식재료]===0인 식재료명이 등장하면 경고(테스트가 탐지). 단호박·요거트 같은 0회 식재료가 가이드 문구에 새지 않는지 회귀.
• 대표 식재료 정비 자체는 C(GROUP_INGREDIENTS)에서 수행 — B는 의존(depends_on C-XX 외부)으로 표기하고 정합 테스트만 보유.

• food-bridge 가이드 stepBehavior에 '단호박' 같은 0회 식재료가 들어가지 않음(C 재료가 토마토·브로콜리 제공).
• exposure-savings why가 빈도 있는 타깃만 인용.

• 0회 식재료 가이드 누설 가드 + 테스트
• freqMap fixture 박제(인계서 실측)
• B/C 경계(B는 식재료 안 만듦) 회귀
• C(GROUP_INGREDIENTS 정비) 의존 표기
• npm test 그린

✅B-11 · coach-guide 테스트 스위트 + 리플레이 픽스처(아린 6통 회귀)테스트 테스트 · 1.5h

• tests/coach-guide.test.ts 신규 — 기존 curriculum.test.ts 헬퍼(row·baseDays·ev·D())와 동일 컨벤션 차용(TODAY 고정·D(n) 상대일).
• 아린 픽스처: focus=table-stage envTablePct 정체(18일 deepen 고착·limping 케이스 — curriculum.ts:194 limping 주석 실증)를 재현해 가이드 mode='pivot' 또는 plateau 정합 확인.
• 수렴 회귀: 같은 decision 6일 연속이라도 arcStage가 ROT 회전(B-03)으로 갈리는지(같은 mode여도 stage 분산) — '6통 당근→미역국 수렴' 가이드측 대응.
• 모호어 회귀: 6 가이드 전부 why에 '요즘/최근' 0건(B-04-4 강화).
• 온보딩 회귀: 가입 다음날 lowData → 환각 결핍 0(B-07-3 강화).
• 리플레이 스타일: 14일 시뮬 루프(replay.test.ts 패턴 차용)로 매일 buildTeachingGuide 호출 → arcStage 6일 창에서 intro 1회 이하(주1회 도입 보장).

• CI prebuild 게이트가 가이드 회귀를 매 머지 검사.
• 향후 엣지 발견 시 이 파일에 case 추가(복리).

• tests/coach-guide.test.ts 신규(기존 컨벤션 차용)
• 아린 6통 수렴/환각/모호어 회귀 박제
• 14일 리플레이 시뮬 그린
• prebuild 게이트 통과(npm test 그린)
• 엣지 추가용 복리 구조

✅C-01 · LetterInput grounding 확장 + GroundingMode 타입코드 코드 · 0.5h

• lib/coach.ts LetterInput에 추가: `groundingMode?: 'merged' | null`, `teachingGuide?: string | null`, `materials?: string | null`, `materialFoods?: string[] | null`(qualityScan 화이트리스트), `mirror?: string | null`, `onboardingMode?: boolean`, `loggedDaysTotal?: number`, `missingInputHints?: string[] | null`.
• export type GroundingMode = 'merged'; 추가.
• 기존 필드(factCards·bridgeFacts·timeseries·recentLoggedDays 등)는 변경 없음 — merged는 이들을 '읽는 방식'만 바꿈.
• 주석에 '★ 모든 grounding 필드는 Letter B 전용 — groundingMode 미설정이면 무시(A 무변경)' 명시.

• 크론이 Letter B용 base를 만들 때 groundingMode:'merged'·teachingGuide·materials·mirror를 채워 composeLetter에 넘긴다.
• Letter A(대조군) base는 이 필드들을 비워(undefined) 기존 경로 그대로 탄다.

• LetterInput에 grounding optional 필드 8개 + GroundingMode 타입 추가
• groundingMode 미지정 시 기존 출력 byte 동일(C-01-1)
• tsc 그린(타입 게이트)
• npm test 그린(prebuild 게이트)

✅C-02 · buildLetterUser merged 분기 — 재료(결정론) 블록 주입코드 코드 · 1.5h

• lib/coach.ts buildLetterUser 안에 `if (b.groundingMode === 'merged')` 분기 추가.
• merged: '[오늘의 재료 — 코드가 매일 검증·회전해 확정. ⚠️ 음식·식재료·조합은 이 목록 안에서만. 목록 밖 조합/음식명을 지어내면 괴식·환각이다]' + b.materials.
• materials가 null이면 기존 bridgeFacts로 폴백(B-에픽 미완 시 안전).
• 기존 530~531줄 작성지침(검증된 추천 목록 안에서만)을 merged에서도 유지(materials를 '검증된 추천'으로 동일 취급).
• merged 분기에 '★ 무엇을 추천할지는 이미 정해졌다 — 너는 어떻게 따뜻하게 쓸지만 결정' 한 줄 추가.

• selectDailyMaterials가 '짜파게티+당근(2), 근거: 당근=상위2%·베타카로틴' 재료 주입 → merged buildLetterUser가 LLM에 못 박음.

• merged 분기가 materials 블록을 주입하고 null이면 bridgeFacts 폴백
• C-02-1~6 전부 그린
• Letter A(레거시) byte 동일(C-01-1) 유지
• npm test 그린(prebuild 게이트)

✅C-03 · buildLetterUser merged — 거울(mirror) 데이터 주입(byte 고정 금지)코드 코드 · 1h

• lib/coach.ts buildLetterUser merged 분기에 `b.mirror ? '[식단 거울 — 아이가 실제 먹은 것/영양 신호. ⚠️ 그대로 베끼지 말고 너의 표현으로 1~2문장에 녹여라(byte 복사 금지). 사실(메뉴·결핍군)은 바꾸지 말 것]\n' + b.mirror : ''` 추가.
• mirror는 coachFacts.buildMealMirror 산출 — 사실(결핍군·추천)은 코드가 못 박은 것.
• mirror 안 추천·결핍군 사실은 materials와 모순되면 안 됨 → 둘 다 selectDailyMaterials 타깃에서 파생(정합 검증=C-09).

• mirror='노랑·주황 채소가 아쉬워요. 짜파게티에 당근을 넣어보세요' → LLM이 '주황빛 채소가 한 발 비어 있더라고요…' 로 재서술.

• merged 분기가 mirror를 데이터로 주입+byte 복사 금지 지시
• C-03-1~4 그린
• Letter A byte 동일 유지
• npm test 그린

✅C-04 · buildLetterUser merged — 두뇌 가이드(teachingGuide) 주입코드 코드 · 1h

• lib/coach.ts buildLetterUser merged 분기에 `b.teachingGuide ? '[오늘의 코칭 방향 — 코드/Sonnet가 정한 교육 의도. ⚠️ 의도·초점은 따르되 문장·도입·예시·톤은 자유롭게(고정 문구 복사 금지)]\n' + b.teachingGuide : ''` 추가.
• teachingGuide가 있으면 arcBlock(weeklyArc) 생략(merged는 가이드 기반 통일).
• 행동 1개 원칙(P7) 유지 지시 추가.

• EPIC B가 진단→유닛 매핑→teachingGuide 텍스트 생성 → merged buildLetterUser가 LLM 가이드로 주입, LLM 자유 작문.

• merged 분기가 teachingGuide를 가이드로 주입+자유작문 지시, arcBlock 상호배타
• C-04-1~5 그린
• Letter A byte 동일 유지
• npm test 그린

✅C-05 · buildLetterUser merged — 온보딩(기록<3일) 분기코드 코드 · 1h

• lib/coach.ts buildLetterUser 안 `if (b.groundingMode==='merged' && b.onboardingMode)` 최우선 분기 → 분석 블록(reds·missing·timeseries·factCards·materials) 전부 생략.
• 온보딩 프롬프트: '[온보딩 — 기록 ${loggedDaysTotal??0}일뿐이라 분석 안 함. ⚠️ 결핍·패턴·영양 분석 절대 금지(환각). 대신 (1)빠트린 입력 안내(${missingInputHints 또는 기본 끼니·거부·환경) (2)배경 없는 즉효 편식 팁 1개]' + pickTip(daySeed).
• P7·따뜻한 톤·점수금지 유지. pickTip(daySeed) 로테이션 재사용.
• onboardingMode 판정은 호출자(크론/buildOnboardingDecision)가 계산해 넘김 — buildLetterUser는 플래그만 신뢰(순수).

• 가입 다음날 기록 1일 → onboardingMode=true → '거부한 음식이나 환경도 남겨주시면 더 정확히 봐드릴게요' + 즉효 팁.

• merged+onboarding이 분석 전부 생략+입력안내+즉효팁만 생성
• C-05-1~6 그린
• Letter A byte 동일 유지
• npm test 그린

✅C-06 · buildLetterUser merged — raw timeseries 강등(사실 인용은 카드만)코드 코드 · 0.75h

• lib/coach.ts buildLetterUser merged 분기에서 timeseries 라벨 변경: 기존 '시계열 사실:' → merged '시계열(참고용 — ⚠️ 여기서 횟수·날짜·패턴 인용 금지. 사실 주장은 아래 사실 카드에서만):'.
• factsBlock(521~523줄) 강화: '편지의 모든 사실(빈도·횟수·환경·거부·메뉴)은 사실 카드에만 근거. timeseries 원문 숫자 인용 금지'.
• 레거시는 timeseries를 기존대로 '시계열 사실'(C-01-1 byte 동일 보장).
• raw ts는 composeLetter가 sanitizeTimeseries/ALLOW_TRANSITION 필터(634줄)를 거친 산출을 받음 — 강등은 라벨·지시 수준.

• timeseries '당근 3일 전 거부'가 있어도 merged LLM은 직접 인용 못하고 factCards '거부: 당근 — 단발 1회'만 사용.

• merged timeseries 라벨 강등 + factCards 유일 출처 강조
• C-06-1~4 그린
• Letter A byte 동일 유지
• npm test 그린

✅C-07 · serializeMaterials — 검증 재료를 LLM 텍스트로 직렬화(lib/coachGrounding.ts)코드 코드 · 1.5h

• lib/coachGrounding.ts 신규 — `export function serializeMaterials(m: { target: string; targetIngredient: string; combos: { dish: string; ingredient: string; score: number }[]; rationale: string; periodFact: string; cousins?: string[] }): string`.
• 출력 포맷: '[오늘 타깃] {target} — {targetIngredient}\n검증된 조합(점수순): {dish+ing(score)}·…\n근거: {rationale}\n기간: {periodFact}\n사촌: {cousins}'.
• combos는 score>=1만 포함(C-09 검증 통과분 — 0=괴식 금지). 점수순 정렬, 상한(최대 4) 절단. 빈 combos면 조합 라인 생략.
• 타깃 식재료명·dish·cousins 외 음식명은 절대 합성 안 함(LLM 지어내기 입구 차단). rationale·periodFact는 입력 그대로 박음(사실 생성 안 함).
• buildRecoFacts(coachRecos.ts — 레거시 bridgeFacts)와 역할 분리되어 공존(둘 다 별개 함수).

• selectDailyMaterials → {target:'비타민A채소',targetIngredient:'당근',combos:[{dish:'짜파게티',ingredient:'당근',score:2}],rationale:'급식 상위2%',periodFact:'최근 7일 중 3일'} → serializeMaterials → merged materials 텍스트.

• serializeMaterials 순수 함수 구현·score>=1 필터·입력 외 음식명 불출현
• C-07-1~9 그린
• tests/coach-grounding.test.ts에 수록(prebuild 게이트)
• npm test 그린

✅C-08 · buildOnboardingDecision — 기록<3일 판정 + 입력 안내 산출(순수)코드 코드 · 1h

• lib/coachGrounding.ts에 `export function buildOnboardingDecision(p: { rows: FactRow[]; loggedDaysTotal: number }): { onboarding: boolean; missingInputHints: string[] }`.
• onboarding = loggedDaysTotal < ONBOARDING_MIN_DAYS(=3).
• missingInputHints: 거부 기록 0건 → '거부한 음식', environment 채워진 행 0 → '식사 환경(영상·자리)', dinner 슬롯 0 → '저녁 끼니' — 비어 있는 카테고리만.
• FactRow 타입은 coachFacts.ts import(refused·environment·slot 컬럼).
• ONBOARDING_MIN_DAYS=3 상수 노출 — coachScenarios recentWindow/low-data-gap 철학과 정합.

• 가입 다음날 rows=[{slot:'breakfast',refused:null,environment:null}], loggedDaysTotal=1 → onboarding=true, hints=['거부한 음식','식사 환경','저녁 끼니'].
• 기록 5일·거부/환경 다 채움 → onboarding=false, hints=[].

• buildOnboardingDecision 순수 함수·임계33·비어있는 항목만 안내
• C-08-1~9 그린
• tests/coach-grounding.test.ts에 수록
• npm test 그린

✅C-09 · verifyComboSafety — 섞기 조합 정합성 검증(괴식 차단)코드 코드 · 1.5h

• lib/coachGrounding.ts에 `export function verifyComboSafety(combos: { dish: string; ingredient: string }[], scoreOf: (dish: string, ing: string) => number): { dish: string; ingredient: string; score: number }[]`.
• scoreOf 주입(테스트=가짜 함수, 런타임=kitGuide/kit-dish-matrix 조회) — 순수성 유지.
• 필터: score >= 1만 통과(0=괴식, 미존 셀=0). '미역국+당근' 같은 비관용 조합은 매트릭스0이라 자동 탈락.
• food-graph pair 궁합 승격은 호출자(EPIC B selectDailyMaterials)가 neighborsOf 결과를 scoreOf에 합성 — 이 함수는 scoreOf 결과만 보는 최종 게이트.
• 통과 결과는 serializeMaterials(C-07) combos 입력이 됨(파이프라인: selectDailyMaterials → verifyComboSafety → serializeMaterials).

• combos=[{짜파게티,당근},{미역국,당근},{볶음밥,당근}], scoreOf 짜파게티2·미역국0·볶음밥2 → 짜파게티·볶음밥만 통과.

• verifyComboSafety 순수 함수·score>=1 필터·괴식 0점 차단
• C-09-1~9 그린(인계서 괴식 '미역국에 당근' 케이스 포함)
• tests/coach-grounding.test.ts에 수록
• npm test 그린

✅C-10 · composeLetter groundingMode 분기 — Letter B 통합 + Letter A 무변경 보장코드 코드 · 2h

• lib/coach.ts composeLetter letterInput 합성(635~642줄)은 이미 `...p.base`로 grounding 필드를 포함 → buildLetterUser 분기(C-02~C-06)가 처리하므로 추가 코드 최소.
• merged에서도 sanitizeTimeseries/ALLOW_TRANSITION 필터(634줄)·detBad·simBadness·verifyLetter 루프(645~693줄) 전부 적용(가드 대칭 S1 — Letter B도 모든 가드 통과).
• onboardingMode면 simBadness 재생성 루프 최대 1회로 제한(데이터 빈약·유사도 의미 낮음).
• Letter A 무변경: groundingMode undefined면 letterInput·buildLetterUser·verifyFacts 모두 기존 분기(C-01-1·C-10-1 byte 동일).

• 크론 Letter B base(groundingMode:'merged'+materials/mirror/guide) → merged 작문+전 가드 통과.
• 동일 크론 Letter A base(grounding 없음) → 기존 v2 편지(대조군).

• composeLetter가 groundingMode로 분기, merged는 전 가드 통과·레거시는 byte 동일
• C-10-1~8 그린(callClaude 모킹)
• Letter A 대조군 무변경 스냅샷 유지
• npm test 그린

✅C-11 · verifyFacts merged 확장 — 거울·재료를 검증 데이터에 합본(무검증 채널 차단)코드 코드 · 1h

• lib/coach.ts verifyFacts merged 분기: b.groundingMode==='merged'면 '검증된 재료(LLM이 쓸 수 있는 것 전부): '+b.materials · '식단 거울 사실: '+b.mirror 라인 추가.
• verifyLetter 입력 facts에 거울·재료가 포함되면 SYSTEM_VERIFY 1번(사실 근거) 항목이 '재료 밖 음식·조합'을 의미 수준으로 잡음(facts에 재료 있어야 대조 가능).
• 레거시 verifyFacts는 기존 라인만(materials/mirror 미추가).

• merged 편지가 재료에 없는 '바나나+멸치'를 썼다 → verifyFacts facts에 재료 목록이 있어 verifyLetter가 위반 적발 → 재생성.

• verifyFacts merged 분기가 materials·mirror를 facts에 합본, 레거시 무변경
• C-11-1~5 그린
• tests/coach-guards.test.ts에 수록
• npm test 그린

✅C-12 · qualityScan — 발행 전 품질축 결정론 스캔(은유·나열·모호기간·재료밖)코드 코드 · 2h

• lib/coachGrounding.ts에 `export function qualityScan(p: { letter: string; materialFoods: string[] }): string[]`(위반 사유 배열, 빈=통과).
• (1) 은유 사전 과용: METAPHOR_CLICHE=/통장|적금|계단|걸음|무대|디딤돌|사슬|풍경|씨앗|새싹/ — 한 편지에 클리셰 은유 2개+ 또는 동일 은유 반복 시 위반.
• (2) 나열 패턴: /어제.{0,6}먹었/·'(을|를) 먹었어요[,·、].{0,20}(을|를) 먹었' — '어제 X 먹고 Y 먹고' 나열 → 위반.
• (3) 모호 기간어: '요즘'·'며칠째'·수치 동반 없는 '최근'/'이번 주' → 위반(개선 F). 수치 동반(최근 7일 중 N일)은 통과.
• (4) 재료 밖 음식명: materialFoods에 없는 구체 음식명이 본문에 등장하면 위반 — 음식명 후보를 도감 어휘로 스캔하되 일반 명사(밥·국·반찬)는 제외.
• 각 위반은 한국어 사유 문자열(재생성 fixNotes로 재사용). 임계·사전 상수 노출. 오탐 방지: 따뜻한 일반론·은유 1개·수치 동반 기간어 통과.

• '입맛은 통장 같아서 노출이 적금처럼'(은유 2개) → 위반.
• '어제 당근 먹고 브로콜리 먹고 시금치 먹었어요'(나열) → 위반.
• '요즘 채소가 비어요'(모호) → 위반 / '최근 7일 중 채소 3일'(수치) → 통과.
• 재료가 당근뿐인데 본문에 '시금치무침' → 재료밖 위반.

• qualityScan 순수 함수·4축(은유·나열·모호기간·재료밖) 검사·오탐 방지
• C-12-1~12 그린
• tests/coach-grounding.test.ts에 수록
• npm test 그린

✅C-13 · composeLetter merged 품질 재생성 루프 — qualityScan 배선코드 코드 · 1.5h

• lib/coach.ts composeLetter merged 분기(verifyLetter 블록 676~693줄 다음)에 qualityScan 패스 추가: `if (base.groundingMode==='merged' && !base.onboardingMode && timeLeft()) { const q = qualityScan({ letter: gen.letter, materialFoods }); if (q.length) { 재생성(fixNotes=q) → 새 산출이 detBad false && simBadness<1 && qualityScan 줄어듦 시만 채택 } }`.
• materialFoods = base.materialFoods(C-01 필드) 또는 materials에서 식재료 토큰 추출.
• 재생성은 generateLetter({...letterInput, fixNotes:q}) — 기존 fixBlock(510~512줄) 재사용.
• 채택 조건: detBad·simBadness·qualityScan 모두 개선/통과(verifyLetter 689줄 패턴 그대로).
• composeLetter 반환에 `quality?: { violations: string[]; regen: boolean }` 추가(altLetter design에 담김).

• merged 첫 생성이 '입맛은 통장' 은유 과용 → qualityScan 위반 → fixNotes 재생성 → 은유 제거본 채택.

• composeLetter merged에 qualityScan 배선·가드 대칭 채택·레거시 무영향
• C-13-1~7 그린(callClaude 모킹)
• Letter A byte 동일 유지
• npm test 그린

✅C-14 · coach-grounding 테스트 스위트 + prebuild 게이트 회귀테스트 테스트 · 1.5h

• tests/coach-grounding.test.ts 신규 — serializeMaterials(C-07)·buildOnboardingDecision(C-08)·verifyComboSafety(C-09)·qualityScan(C-12) 순수 함수 테스트.
• tests/coach-guards.test.ts에 buildLetterUser merged 분기(C-02~C-06)·verifyFacts merged(C-11)·byte 동일 회귀(C-01-1) 추가.
• composeLetter 통합(C-10·C-13)은 callClaude를 vi.mock으로 고정 응답 모킹 + 전달 user 텍스트를 spy로 단언.
• Letter A byte 동일: groundingMode 없는 대표 fixture로 buildLetterUser 출력 스냅샷 → 변경 후 일치.
• fixtures/ 기존 디렉터리 재사용. vitest 실행으로 그린 확인 후 머지(불변 원칙 ①).

• npm test(prebuild 게이트) → coach-grounding 신규 + 기존 7파일 전부 그린.
• Letter A 회귀 스냅샷이 깨지면 = 대조군 오염 → 즉시 차단.

• coach-grounding 신규 스위트 + coach-guards 추가 테스트 전부 그린
• 기존 220개 무파손(회귀)
• Letter A byte 동일 스냅샷 존재·통과
• npm test prebuild 게이트 그린(머지 전 조건)

✅D-01 · 은유 클리셰 사전 + metaphorOveruse(L) 검출기코드 코드 · 1h

• 신규 파일 lib/coachQuality.ts 생성. lib/coach.ts의 FORBID_TIME/fruitSaltyMix와 동일한 '순수 정규식 검출' 패턴을 따른다(fs/HTTP 불사용).
• export const METAPHOR_CLICHES: { key: string; re: RegExp }[] — 인계서 G의 사전을 근거화: 통장/적금/저금, 문(을 열다), 계단(을 오르다), 걸음/한 걸음, 무대, 디딤돌, 사슬/체인, 길(을 걷다)/여정, 풍경. '걸음'은 '한 걸음씩' 같은 코칭 상투구라 비중 큼.
• export function metaphorOveruse(L: string): boolean — (1)서로 다른 key가 2종 이상 매칭되면 true (2)같은 key가 2회 이상 등장하면 true. 단일 key 1회는 false(오탐 방지).
• 동음 오탐 가드: '문'은 '문득/방문/주문/질문/문제'를 제외('문을 열' 형태로 한정), '길'은 '길어/길게/기다림' 제외('새로운 길'·'먹는 길' 형태로 한정).
• 임계는 파일 상단 튜닝 상수로(예 DISTINCT_METAPHOR_MAX=1, SAME_METAPHOR_MAX=1).

• 6/8 아린 v3 편지처럼 '식습관은 통장에 차곡차곡 쌓이는 적금과 같아요. 한 걸음씩 계단을 오르듯…' → true.
• '아린이가 새로운 맛에 마음을 여는 작은 문을 하나 열었네요' → false(은유 1종 1회).
• 은유 없는 구체 편지 '어제 저녁 당근볶음밥을 반 그릇 비웠어요' → false.

• lib/coachQuality.ts에 metaphorOveruse 구현·export
• 순수함수로 단독 테스트(LLM mock 불필요)
• D-01-1~12 전부 그린
• npm test 그린(prebuild 게이트)

✅D-02 · '어제 X 먹었어요' 나열 패턴 검출 mealEnumeration(L)코드 코드 · 1h

• 시점어 사전 AGO_WORD = /어제|그제|그저께|오늘|아침|점심|저녁|[0-9]+일\s*전/, 동사 ATE = /먹(었|었어요|었네요|음)|드셨|비웠|남겼/.
• 문장 분리는 coach.ts의 L.split(/[.!?。\n]/) 패턴 재사용. 한 문장에 시점어+ATE 동시 매칭 문장 개수 count. count>=2면 true(임계 ENUM_MAX=1).
• 추가 패턴: 쉼표/가운뎃점으로 명사 3개+ 나열 + 끝에 ATE 1개('어제 당근, 시금치, 두부를 먹었어요') = 시점어 동반 시 true.
• FORBID_TIME(coach.ts)과 역할 분리: FORBID_TIME=환각 기간어, 이건 데이터 나열 패턴. 둘 다 품질 스캐너(D-05)에서 합쳐 호출.

• '어제 점심에 카레를 먹었어요. 그제 저녁엔 볶음밥을 먹었네요. 오늘 아침엔 빵을 먹었어요.' → true.
• '어제 저녁 당근볶음밥을 처음 비웠다는 게 정말 반가워요' → false.
• 데이터 사실 0개 편지 → false.

• lib/coachQuality.ts에 mealEnumeration 구현·export
• 순수함수 단독 테스트
• D-02-1~11 전부 그린
• FORBID_TIME과 중복 검출하지 않음 확인
• npm test 그린

✅D-03 · 모호 기간어 검출 vagueTimeWord(L) (FORBID_TIME과 분리)코드 코드 · 0.5h

• VAGUE_TIME = /요즘|요새|근래|최근|이번\s*주|얼마\s*전|한동안|당분간|며칠째/. 단 직후 12자 내 [0-9]+\s*(일|번|회|가지) 동반 시 면제.
• FORBID_TIME(coach.ts:379)은 이미 '지난달·N개월·N일간'을 잡으므로 중복 금지 — vagueTimeWord는 수치 없는 정성 기간어만 담당.
• 구현: VAGUE_TIME 전체 매칭 위치 직후 12자 윈도우에 수치 단위 없으면 위반 1건. >=1이면 true.
• 임계 상수 없음(0건 vs 1건+ 이진).

• '요즘 채소를 잘 안 드시네요' → true.
• '최근 7일 중 비타민A 채소가 3일이었어요' → false.
• '이번 주 중 콩류가 2번 나왔어요' → false.

• lib/coachQuality.ts에 vagueTimeWord 구현·export
• 수치 동반 시 면제 로직 단독 테스트
• FORBID_TIME과 역할 중복 없음 확인
• D-03-1~11 그린
• npm test 그린

✅D-04 · 재료 밖 음식명 스캔 offMaterialFood(L, allowed)코드 코드 · 1.5h

• DISH_SUFFIX = /([가-힣]{1,6}(찌개|국|탕|볶음|구이|조림|찜|밥|죽|전|무침|나물|샐러드|스프|파스타|면|빵|떡))/g 로 토큰 추출.
• allowed 정규화: 호출자가 bridgeFacts 텍스트·favoriteFoods·popularDishesFor 결과·SNACK 예시를 모아 넘긴다. allowed 내 부분문자열 포함(includes) 매칭이면 통과.
• 일반 명사 ALLOW_GENERIC = ['밥','국','죽','반찬','간식','식사','끼니'] 단독은 면제(구체 음식명만 검사).
• 반환은 위반 음식명 배열(중복 제거) — D-05 스캐너가 .length>0이면 위반으로 처리하고 hint에 '목록 밖 음식: X' 주입 가능.

• allowed=['순두부찌개','두부','볶음밥'], 본문='마파두부로도 자주 먹어요' → ['마파두부'].
• allowed=['순두부찌개','볶음밥','두부'], 본문='볶음밥에 두부를 섞고 순두부찌개도' → [].
• 음식명 없는 환경 코칭 편지 → [].

• lib/coachQuality.ts에 offMaterialFood 구현·export
• 화이트리스트 부분일치 로직 단독 테스트
• 식재료명 과탐 방지 케이스 통과
• D-04-1~12 그린
• npm test 그린

✅D-05 · letterQualityBad(L, opts) 통합 품질 스캐너코드 코드 · 1h

• export function letterQualityBad(L, opts): metaphorOveruse→'은유 과용', mealEnumeration→'데이터 나열', vagueTimeWord→'모호 기간어(수치로)', offMaterialFood(L,opts.allowedFoods||[]).length>0→'목록 밖 음식: '+joined.
• letterDeterministicBad(coach.ts:392)와 동일 시그니처 철학(순수·부작용 없음). reasons 반환으로 D-07이 verify hint·fixNotes로 변환.
• opts.allowedFoods 미제공 시 offMaterialFood 검사 생략(allowed 없으면 전부 위반으로 보면 과탐 — 안전 skip).
• 튜닝 상수는 D-01~D-03 개별 임계 재사용, 이 함수는 OR 조합만.

• 은유 과용 편지 → { bad:true, reasons:['은유 과용'] }.
• 은유+나열 동시 → { bad:true, reasons:['은유 과용','데이터 나열'] }.
• 깨끗한 편지 → { bad:false, reasons:[] }.

• lib/coachQuality.ts에 letterQualityBad 구현·export
• D-01~D-04 조합 OR 함수로 순수
• allowedFoods 머제공 시 음식명 검사 skip 안전장치
• D-05-1~10 그린
• npm test 그린

✅D-06 · 검증 합본 입력 빌더 — 거울·추천·슬롯값을 본문과 1패스로코드 코드 · 1h

• 거울 = coachFacts.buildMealMirror 산출(coachFacts.ts:73, compileFactCards가 mirror 반환:293). 추천 = coachRecos.buildRecoFacts(...).text 또는 bridgeFacts(route.ts:664).
• composeVerifiableText는 [letter, mirror, recoText].filter(Boolean).join('\n')로 합본. Letter B는 본문뿐 아니라 거울·추천 슬롯도 발행되므로 셋 다 검사망에 든다.
• 주의: 합본은 '검증 입력'에만 쓰고 실제 발행 본문(letter)은 변형하지 않는다. 검사 통과 후 각 슬롯 그대로 저장.
• D-08 composeLetterB 재생성 루프가 detBad·qualityBad를 이 합본 텍스트 기준으로 호출하도록 배선.

• 본문은 깨끗하나 거울이 '요즘 채소가 비어요'(모호어)면 합본 검사에서 vagueTimeWord 적발 → 재생성.
• 추천 텍스트에 목록 밖 괴식 음식명이 새어들면 offMaterialFood 적발.
• 셋 다 깨끗하면 합본도 통과.

• composeVerifiableText 구현·export
• 합본이 슬롯 숨은 위반을 검사망에 올림 확인(통합 테스트)
• 발행 본문은 합본로 변형되지 않음
• D-06-1~7 그린
• npm test 그린

✅D-07 · verifyLetter 품질 사유 hint 주입 + allowedFoods 파서(B 전용)코드 코드 · 1h

• allowedFoodsFromBridge: bridgeFacts 텍스트에서 '인기 음식: A·B'·'사촌 X(또래 인기: Y)'·'궁합 Z' 패턴과 favoriteFoods를 먹어 토큰 set 반환. buildRecoFacts 출력 포맷(coachRecos.ts:113,130,133) 근거.
• qualityBad = letterQualityBad(composeVerifiableText(...), { allowedFoods }) 산출. bad면 generateLetter({...letterInput, fixNotes:[...qualityBad.reasons]})로 재작성(det 루프와 동일 패턴 coach.ts:650).
• verifyLetter SYSTEM_VERIFY(coach.ts:575) LLM 의미 검증은 유지. 품질축은 결정론(빠르고 무료)라 LLM 콜 전에 먼저 거른다.
• ★Letter B 전용 — composeLetterB 시그니처에 allowedFoods/qualityGate를 두고, Letter A 경로(composeLetter)는 파서/게이트 미적용로 무변경.

• B 생성본 은유 과용 → reasons=['은유 과용'] → fixNotes 주입 재작성 → 깨끗해지면 채택.
• bridgeFacts '[오늘 타깃] 두부 (인기 음식: 순두부찌개·된장국)' → allowedFoods=['순두부찌개','된장국', favoriteFoods…].
• A 경로는 무변경 → byte 동일.

• allowedFoodsFromBridge 파서 구현·단독 테스트
• 품질 결정론 게이트가 LLM 콜 전에 수행
• A 경로 byte 동일 회귀 확인
• D-07-1~7 그린
• npm test 그린

✅D-08 · composeLetterB — Letter B 통합 작성기(개선 A~I 적용·가드 대칭)코드 코드 · 2h

• composeLetter(coach.ts:622) 본문을 복제하거나 공용 내부 함수로 리팩터. detBad 클로저(:648) 옆에 qBad=(L)=>letterQualityBad(composeVerifiableText({letter:L, mirror:p.mirror, recoText:p.base.bridgeFacts}), {allowedFoods:p.allowedFoods}).bad 추가.
• det 재생성 루프(:650), 유사도 루프(:663), 검증자 채택(:689) 세 곧 '채택 조건'에 && !qBad(g.letter) 추가 — 어떤 경로의 재생성도 품질축 재통과해야 채택(S1 대칭).
• 품질 단독 위반 시 전용 재작성 루프(최대 2회): for dk<2 && qBad(gen.letter) && timeLeft() → generateLetter({...letterInput, fixNotes: quality reasons}).
• 반환 객체에 quality 필드(어드민 D-11·컨텍스트 D-10용). modelUsed·verify는 기존 유지.
• ★A 무변경: Letter A는 기존 composeLetter 호출 그대로. 비교 대조군 보존.

• B 생성본 은유 과용 → 품질 루프 재작성 → 통과본 채택, quality.regen=true.
• 유사도 재생성본이 품질 bad면 미채택(원본 유지) — S1.
• deadline 임박 시 품질 루프 생략하고 발행(S7).

• coach.ts에 composeLetterB 구현·export
• 세 채택 조건(det·유사도·검증) 전부에 !qBad 추가(S1 대칭)
• Letter A composeLetter byte 동일 회귀 테스트 통과
• D-08-1~10 그린(LLM mock)
• npm test 그린(prebuild 게이트)

✅D-09 · 기존 가드 회귀 테스트 보강 + 품질축 fixture테스트 테스트 · 1h

• tests/fixtures에 letter-v3-convergent.txt(6/8 통장/적금 은유 편지), letter-v2-good.txt(구체·은유1회·수치 동반) 추가.
• v3 fixture → letterQualityBad.bad=true, v2 fixture → bad=false 단언(품질축이 양질 편지를 오탐하지 않음 = 핵심).
• vitest describe 구성은 기존 coach-guards.test.ts 스타일(it.each 적대 케이스). 순수함수라 LLM mock 불필요.
• letterDeterministicBad와 letterQualityBad가 동일 편지를 이중 검출해도 무해함을 명시하는 케이스.

• v3 fixture를 품질 스캐너에 넣으면 적발(처치 효과 증명).
• v2 양질 fixture는 통과(오탐 0).
• 기존 det 가드 케이스 전부 그린 유지.

• tests/coach-quality.test.ts 신규 + fixture 2개 추가
• v3=bad, v2 양질=통과(오탐 0) 증명
• 기존 coach-guards 케이스 불변
• 신규+기존 전체 npm test 그린(prebuild 게이트)

✅D-10 · route.ts Letter B 합본·품질 컨텍스트 배선 + altLetter 저장코드 코드 · 2h

• route.ts compose 블록(:683 composeLetter 호출 직후)에 compare 분기. isCompare(cid) = (process.env.COACH_COMPARE_CHILDREN||process.env.COACH_V3_CHILDREN||'').split(',').map(s=>s.trim()).includes(cid).
• compare면 아린은 v3 순수 조립을 하지 않음(인계서: compare 모드가 v3 조립 대체). A=기존 v2 composeLetter, B=composeLetterB({base, precomputed, allowedFoods, mirror:fc.mirror, detInput, detForbid, deadlineMs, daySeed, cidHash}).
• altLetter = { letter:B.letter, oneliner:B.oneliner, design:'hybrid-v2-llm', mirror:fc.mirror, materials:bridgeFacts, quality:B.quality, verify:B.verify, plan:B.plan }. finalCtx.altLetter=altLetter. 메인 letter/oneliner=A 그대로.
• fc.mirror는 compileFactCards 반환(coachFacts.ts:293). allowedFoods는 allowedFoodsFromBridge(bridgeFacts, favoriteFoods)(D-07).
• ★불변 원칙: 스키마 변경 0(context jsonb에 altLetter 키 추가만). SQL 실행 불필요. A 무변경 — 메인 발행 경로 byte 동일.

• 아린 cron → A(v2)·B(하이브리드) 동시 생성 → context.altLetter에 B 저장 → 어드민이 둘 비교.
• 비교 코호트 외 자녀 → 기존 경로 그대로(altLetter 없음).
• B가 어드민 피드백에서 이기면 J 에픽에서 전 자녀 승격.

• route.ts에 isCompare 분기 + composeLetterB 호출 + altLetter upsert
• 메인 letter/oneliner=A byte 동일(대조군 보존)
• 스키마 변경 0(context jsonb 키만 추가, SQL 미실행)
• 비교 외 자녀 기존 경로 무변경
• D-10-1~9 그린
• tsc 0·build 0·npm test 그린

✅D-11 · 어드민 검증·품질 위반 보고(cron_runs.issues + altLetter.quality)운영 코드 · 0.5h

• route.ts:693 issues.push('검증위반 발행...') 패턴을 품질축으로 확장: if(altLetter && altLetter.quality?.bad) issues.push('B품질위반 '+nickname+': '+altLetter.quality.reasons.slice(0,2).join('/')).
• altLetter.quality.regen이면 context에 '품질 재작성 수행' 기록(재작성으로 통과했는지 vs 못 통과하고 발행했는지 구분).
• 기존 simToPrev·repeatAlert(route.ts:687-691)는 A 기준 유지, B는 altLetter.quality로 별도 노출(대조군 비교).
• 운영 DoD: 카나리아 3일간 어드민에서 B 품질 위반율·재작성율·A대비 피드백(👍/👎/🔁 letter_feedback) 관찰.

• B가 품질 위반인 채 발행(재작성 실패) → issues에 'B품질위반' → 모니터에서 즉시 포착.
• B가 재작성으로 통과 → context에 regen 기록 → 게이트 효과 측정.
• 어드민에서 A vs B 나란히 비교 → 이사님 피드백 수집.

• route.ts issues + context.altLetter.quality에 B 품질 결과 노출
• A 기준 repeatAlert 무변경
• B 생성 실패 시 노이즈 없음(null 가드)
• 카나리아 3일 모니터 후 전 자녀 승격 판단(운영)
• D-11-1~5 그린·npm test 그린

✅E-01 · compareEnabled 판정 함수 — COACH_COMPARE_CHILDREN(기본=COACH_V3_CHILDREN 재활용)코드 코드 · 0.5h

• lib/coachDaily.ts에 export function compareEnabled(env: { COACH_COMPARE?: string; COACH_COMPARE_CHILDREN?: string; COACH_V3_CHILDREN?: string }, childId: string): boolean 추가
• 본문: if (env.COACH_COMPARE === '1') return true; const list = (env.COACH_COMPARE_CHILDREN || env.COACH_V3_CHILDREN || '').split(',').map(s=>s.trim()).filter(Boolean); return list.includes(childId);
• 기존 v3Enabled(20행)과 동일한 split/trim/filter 관용구를 그대로 따라 일관성 유지 — 두 함수가 코호트 파싱 로직을 공유하도록 내부 헬퍼 parseCohort(env, primary, fallback) 추출 고려(중복 제거)
• process.env를 직접 읽지 않고 인자로 env를 받는 순수 함수(단독 테스트 가능)
• 아린 id 43942d34-b339-4bbd-978a-ec3f6a877031는 하드코딩하지 않음 — env로만 지정(테스트 fixture에서 주입)

• 크론이 자녀 루프에서 cid가 compare 대상인지 분기할 때 호출
• 이사님이 Vercel env에서 COACH_COMPARE_CHILDREN을 지우면 즉시 전 자녀가 기존 경로로 롤백

• 순수 함수로 process.env 미참조(단독 테스트 통과)
• E-01 테스트 12개 그린
• npm test 전체 그린(prebuild 게이트)
• v3Enabled 회귀 없음(기존 coach 테스트 통과)

✅E-02 · Letter B 빌더 모듈 lib/coachCompare.ts — buildLetterB 오케스트레이터 시그니처·폴백 골격코드 코드 · 1.5h

• lib/coachCompare.ts 신규: export type AltLetter = { letter: string; oneliner: string; design: Record<string, unknown>; mirror: string | null; materials: unknown; guide: unknown; verify: { ok: boolean; violations: string[] } | null; modelUsed: string; llmCalls: number }
• export async function buildLetterB(args: { childName: string; ageBand: string; rows: CRow[]; today: string; freqMap: FreqMap; likedIng: string[]; reds: string[]; missing: string[]; groupSignals: ...; recentBMaterials: { food: string; date: string }[]; pastBLetters: { date: string; letter: string }[]; daySeed: number; cidHash: number; deadlineMs?: number; callClaude: typeof callClaude }): Promise<AltLetter | null>
• 의존 함수는 인자로 주입 가능하게(callClaude 등) — route.ts의 import를 모듈이 끌어오지 않고 테스트에서 스텁 가능
• 단계 순서를 try/catch로 감싸 어느 단계든 throw 시 null 반환 + 사유 문자열을 result에 못 담으면 console.warn — route.ts가 issues.push로 노출
• deadlineMs 넘으면(Date.now()>=deadlineMs) LLM 호출 단계 진입 전 null 반환(A만 발행 — S7 정신)
• ★중요: selectDailyMaterials·buildTeachingGuide·composeLetterB·verifyLetterQuality는 sibling EPIC(B·가이드·G) 산출물 — TBD(확인 필요): 본 EPIC은 그 시그니처에 맞춰 어댑터로 호출하고, 미구현 동안은 의존 EPIC 머지 전까지 import 스텁(throw 'not ready')로 두되 buildLetterB는 null 폴백을 보장한다
• 이 모듈은 route.ts의 어떤 전역 상태도 변경하지 않음(순수 오케스트레이션 — DB 쓰기는 route.ts가 담당)

• 크론 compare 분기에서 buildLetterB(...) 한 줄 호출 → altLetter 또는 null
• 의존 EPIC 미완성 단계에서도 빌드·테스트 그린(폴백 null)

• buildLetterB가 throw하지 않음(항상 AltLetter|null)
• E-02 테스트 8개 그린(의존 단계는 스텁)
• TBD 표기된 sibling 시그니처는 의존 EPIC 머지 시 어댑터 정합 재확인
• npm test 그린

✅E-03 · freqMap 본경로 배선 — 죽은코드 부활(C 의존)코드 코드 · 0.75h

• route.ts 100~101행 freqMap 로드는 그대로(let freqMap: FreqMap = {}; try{ ... }catch{})
• compare 분기에서 buildLetterB({ ..., freqMap, ... }) 인자로 전달
• freqMap이 본경로(B의 selectDailyMaterials)에 실제 닿는지 — 테스트로 'freqMap 비어있으면 kit-matrix 폴백, 차 있으면 빈도 가중'을 검증(C EPIC의 가중 랭킹이 freqMap을 소비)
• Letter A의 buildRecoFacts(...freqMap) 호출(664행)은 손대지 않음 — A는 대조군
• 실측 빈도 주석: 당근184(상위2%)·토마토42·근대11·단호박0회 — fixture에 이 값 일부 반영해 빈도 가중이 단호박을 떨어뜨리는지 확인(I EPIC 정합)

• compare 자녀의 B 재료 선택이 급식빈도 상위 식재료를 우선
• freqMap JSON 누락 배포에서도 B가 kit-matrix 폴백으로 동작(크래시 없음)

• freqMap이 B 본경로에 닿음(통합 테스트 증명)
• A 경로 무변경 확인(회귀 테스트 그린)
• freqMap JSON 누락에도 크래시 없음
• C EPIC(가중 랭킹) 머지 후 빈도 가중 실동작 재확인

✅E-04 · compare 분기 — Letter A(v2 그대로) 경로 보존·격리코드 코드 · 1h

• route.ts 502행 if (anchor && v3Enabled(...)) 게이트 앞에 compare 우선 분기: const isCompare = compareEnabled(process.env, cid); if (isCompare) { /* v3 조립 건너뜀 — A는 레거시 v2, B는 buildLetterB */ }
• v3Enabled 분기는 isCompare일 때 진입하지 않게(else if 또는 !isCompare 가드) — '아린은 더 이상 v3 블록 조립 안 함'(브리프 ⑧) 구현
• 결과: isCompare 자녀는 v3Ctx가 null로 남아 650행 if(!v3Ctx) 레거시 v2 생성 경로 진입 → letter=out.letter, oneliner=out.oneliner, verifyCtx=out.verify (A = v2 그대로)
• A 경로의 어떤 입력(base·precomputed·detForbid)도 compare 때문에 바뀌지 않음 — B 빌드는 별도 변수(altLetter)에만 영향
• 비-compare 자녀는 분기 자체가 없으니 완전 무변경(additive 원칙)

• 아린(compare): A=v2 composeLetter, v3 조립 미발동
• 타 자녀(non-compare·v3 카나리아): 기존 v3 조립 그대로
• 타 자녀(레거시): 무변경

• A 경로가 compare on/off에 무영향(회귀 테스트)
• compare 자녀에서 v3 조립 미발동(통합 테스트)
• B 실패가 A 발행을 막지 않음
• npm test 그린

✅E-05 · compare 분기 — Letter B 호출·daySeed/cidHash·재료 회전 입력 준비코드 코드 · 1h

• recentBMaterials 소스: compare 전용으로 최근 3~7일 coach_letters.context.altLetter.materials.food를 추출(B의 3일내 재사용 금지 가드 입력)
• daySeed·cidHash는 438~439행과 동일 산식 재사용(중복 계산 피하려면 변수 위로 끌어올림)
• likedIng(300행)·favoriteFoods(298행)·reds(302)·fg.missing(303)·computeGroupSignals(byDay,catOf)(531행 패턴) 전달
• pastBLetters: 최근 5일 context.altLetter.letter(B 자체의 연속성·반복 회피용 — A의 pastLetters와 분리)
• deadlineMs = runStart + TIME_BUDGET_MS - 4000(683행 composeLetter와 동일 기준 — 단 A가 먼저 예산을 쓰므로 잔여 기준으로 재계산, E-08 참조)
• B 호출은 A 발행 코드(696~731행 upsert) 전 또는 후 — 순서는 E-06에서 확정(altLetter는 같은 row의 context에 합본)

• B 재료가 최근 3일 B 이력을 보고 회전(당근→치즈→시금치)
• B의 작문 연속성은 A가 아니라 과거 B 편지를 참조

• B가 자체 재료·작문 이력을 받아 회전·반복 회피 입력 충족
• 추가 쿼리는 compare 자녀에만(타 자녀 무영향)
• E-05 테스트 7개 그린
• npm test 그린

✅E-06 · context.altLetter 저장 — 스키마 변경 0, 메인 letter/oneliner=A 유지코드 코드 · 0.75h

• 719행 upsert의 context: finalCtx를 { ...finalCtx, altLetter } 로 확장(compare 자녀만)
• altLetter 페이로드 = E-02 AltLetter 결과를 그대로(letter/oneliner/design/mirror/materials/guide/verify/modelUsed/llmCalls) + design 안에 어떤 개선(A~I) 경로 탔는지 플래그
• 메인 컬럼 불변: letter=A, oneliner=A.oneliner, source_hash=srcHash(368행) — B는 context에만
• buildLetterB null → altLetter: { failed: true, reason } (어드민이 B 실패율 모니터)
• context jsonb 크기 가드 — altLetter.materials/guide는 요약본만(원본 거대 객체 금지), letter 본문은 1회 저장(중복 X)
• onConflict 'child_id,letter_date'는 그대로 — 하루 1 row에 A·B 공존

• 어드민 스레드가 한 row에서 A·B를 나란히 렌더(👍/👎/🔁 비교)
• B 실패 시에도 row는 A로 저장되고 altLetter.failed로 가시화

• DB 컬럼·테이블 변경 없음(SQL 불요 — 점심 사고 교훈상 SQL 미동반 확인)
• 메인 letter/oneliner=A 불변(회귀)
• B 실패도 row 저장됨
• E-06 테스트 7개 그린·npm test 그린

✅E-07 · 아린 진도 영속 — compare 모드에서 curriculum_progress·weekly_plans 일관성코드 코드 · 1h

• compare 분기에서 진도 로드(505행 curriculum_progress select)·decideDailyV3(532행) 호출은 유지 — 결정(unit/mode/step)은 B의 teaching guide 입력
• 진도 upsert(540~543행)·피벗 영속(546~548행)·사실 원장 승계(550~552행)는 compare에서도 실행 — '진도 영속'
• 단 assembleLetter(561행)·v3 letter 발행은 compare에선 건너뜀(B는 LLM 작문) — dr.decision/dr.updates만 buildLetterB(guide 입력)로
• decideDailyV3 결과를 altLetter.design.decision에 기록(어드민 검증)
• upsert error 검사(supabase는 throw 안 함 — 2026-06-11 교훈) → issues.push
• TBD(확인 필요): B의 selectDailyMaterials/buildTeachingGuide가 decision을 입력으로 받는지 sibling EPIC 시그니처 확정 후 배선 — 받지 않으면 진도는 '영속만' 하고 B 재료는 영양 신호 기반

• 아린이 compare로 전환돼도 진도 단계가 advance/deepen 흐름을 잃지 않음
• 내일 크론이 어제 진도를 이어받아 연속(W24 goals 영속과 동일 원리)

• compare에서 진도·닻이 영속(2일 연속 fixture 통과)
• assembleLetter 미발동(B는 LLM 작문)
• upsert error 가시화(issues)
• SQL 신규 없음(기존 테이블 재사용 — 점심 사고 교훈상 DDL 불요 확인)
• npm test 그린

✅E-08 · 시간예산·데드라인 — 2통이라 비용 2배, A 우선·B 잔여예산 게이트코드 코드 · 0.75h

• A 발행(696~731 upsert)은 B 빌드와 무관하게 항상 수행 — B는 A 발행 전/후 어디든 A를 막지 않음
• B 게이트: const bBudgetLeft = TIME_BUDGET_MS - (Date.now()-runStart); if (isCompare && bBudgetLeft > 12_000) { altLetter = await buildLetterB({..., deadlineMs: runStart + TIME_BUDGET_MS - 2000}); } else if (isCompare) { altLetter = {skipped:true}; }
• B의 12s 임계는 H-02 주석(회고 12s 잔여 기준)과 동일 보수치 재사용
• 아린 1자녀라 전역 루프 시간(225행 skippedTime 가드)에 영향 미미 — 단 B가 예산 먹어 다음 자녀를 굶기지 않게 B 게이트가 전역 가드와 별개로 동작
• altLetter.skipped/failed/ok 3상태를 어드민이 구분(B 미발행 사유 가시화)
• B의 LLM 콜 수(llmCalls)를 cron_runs.meta에 합산 기록(비용 모니터)

• 크론이 늦게 시작돼 잔여 예산 부족 → A만 발행, B는 skipped(다음날 재시도)
• 정상 시간대 → A·B 둘 다 발행

• A는 어떤 경우든 발행(B가 예산 먹어도)
• B는 잔여 예산 게이트 통과 시에만 호출
• B 콜 수 비용 모니터에 기록
• E-08 테스트 7개 그린·npm test 그린

✅E-09 · 어드민 검증 메타 — context.altLetter.design 스냅샷·repeatAlert·verify 합본코드 코드 · 0.5h

• altLetter.design = { decision: dr.decision, materials: 재료 선택 결과(food+reason), verify: B 품질검증 결과(G EPIC), simToPrevB: B끼리 letterSimilarity 최대값, repeatAlertB: simToPrevB>=0.6, model: B.modelUsed, llmCalls }
• simToPrevB는 pastBLetters(E-05)와 letterSimilarity(coach.ts) 재사용 — A의 simToPrev(687행)와 동일 함수, B 이력 기준
• verify 위반(품질축: 은유 클리셰·나열 패턴·모호 기간어·재료 밖 음식)이 있으면 issues.push(`B검증위반 ${meta.nickname}: ...`) — 693행 A 패턴 평행
• design.paths: B가 실제 탄 개선(A 조합검증·F 수치·G 품질검증 등) 플래그 배열 — 어드민이 '이 편지는 어떤 가드를 통과했나' 확인
• 이 메타는 저장만(발행 결정에 재영향 없음 — fail-open, A의 verify 패턴과 동일)

• 어드민이 B의 추천 근거('당근=급식 상위2%·베타카로틴')를 row에서 확인
• B가 검증 그린인데도 이사님 평가 👎면 design.verify로 '게이트는 통과했다'를 대조

• design 스냅샷이 재료·근거·진단·검증·반복을 모두 담음
• B 위반이 issues로 가시화(A와 평행)
• 메타가 발행 결정에 재영향 없음(fail-open)
• E-09 테스트 8개 그린·npm test 그린

✅E-10 · compare 통합 리플레이 — 아린 fixture 2일 연속 A≠B·진도 영속·재료 회전테스트 테스트 · 1.5h

• tests/fixtures/compare-arin.json: 아린 14일 meal_logs·기존 coach_letters(altLetter 포함)·curriculum_progress·weekly_plans — replay.test.ts fixture 구조 참고
• supabase 클라이언트를 메모리 스텁으로(기존 replay 하네스 패턴) — from().select()/upsert() 캡처
• 불변식 1: 메인 letter(A)는 compare on/off로 동일(대조군 보존)
• 불변식 2: context.altLetter.letter ≠ 메인 letter(B는 다른 편지)
• 불변식 3: 2일차 추천 식재료가 1일차와 다름(B 3일내 재사용 금지 — B EPIC 가드 통합 확인)
• 불변식 4: 2일차 진도가 1일차 step 승계(영속)
• 불변식 5: B 괴식 조합 0건(A 조합검증 통합 — '미역국에 당근' 미발생)
• 불변식 6: A·B 둘 다 발행되거나(예산 충분), 예산 부족 시 A만+altLetter.skipped
• 리플레이가 통합버그를 잡으면 fixture+테스트(red→green)+수정(불변 원칙③ 복리)

• CI/prebuild에서 compare 회귀 자동 차단
• B 개선 EPIC(A~I) 머지 후 통합 동작을 이 하네스가 한 번에 검증

• fixture 기반 2일 연속 리플레이 그린
• 불변식 6종 전부 박제(A보존·B상이·재료회전·진도영속·괴식0·예산폴백)
• 리플레이가 적발한 통합버그는 red→green으로 수정(복리)
• prebuild 게이트(npm test)에 포함돼 자동 회귀 차단

✅E-11 · compare 운영 안전·롤백·라이브 무영향 확인운영 운영 · 0.75h

• 배포 전: env 미설정 상태로 npm run build·npm test 그린(prebuild 게이트)
• 라이브-세이프 시뮬: GET /api/cron/coach?child=43942d34-...&date=2026-06-10 (CRON_SECRET 인증, force 미사용=캐시 존중) — A·B row 확인
• 타 자녀 무영향: compare off 자녀 1명을 ?child로 시뮬해 산출이 배포 전과 동일(diff 0)임을 확인
• 롤백 절차 문서화: Vercel env COACH_COMPARE_CHILDREN 삭제 → 다음 크론부터 아린도 기존 v3 카나리아(COACH_V3_CHILDREN) 또는 v2로 복귀
• 비용 모니터: cron_runs.meta.compareLlmCalls·B failed/skipped 비율을 3일 관찰 후 승격 판단(어드민 피드백 👍/👎/🔁)
• SQL 없음 확인 — 본 EPIC 전 원자가 jsonb context만 사용(점심 사고 교훈: DDL 동반 없음을 명시)

• 배포 직후 아린만 2통, 타 자녀는 평소대로
• B가 비싸거나 불안정하면 env 삭제로 즉시 끔

• env 미설정=기존과 byte 동일(additive 입증)
• 라이브 시뮬에서 A·B 2통 생성 확인
• 타 자녀 diff 0
• env 토글 롤백 절차 확립·SQL 없음 확인
• 3일 모니터 후 어드민 피드백으로 승격 판단(전 자녀 전개는 별도 결정)

✅F-01 · altLetter 추출·검증 순수 함수 lib/altLetter.ts코드 코드 · 1h

• 신규 `web/lib/altLetter.ts`: `export type AltLetter = { letter: string; oneliner: string | null; design?: string | null; mirror?: string | null; materials?: string[] | null }`
• `export function pickAltLetter(context: Record<string, unknown> | null | undefined): AltLetter | null` — context.altLetter 추출. `app/api/cron/coach/route.ts`의 context 스냅샷 키 컨벤션(letter/oneliner/mirror/decision) 그대로 따른다
• 검증: `altLetter`가 객체이고 `typeof altLetter.letter === 'string' && altLetter.letter.trim().length > 0` 일 때만 반환. oneliner는 string 아니면 null로 정규화
• `materials`는 배열이고 원소가 string일 때만 통과, 아니면 null. design은 string 아니면 null
• 부수효과 0(순수 함수) — 입력 context를 변형하지 않음(spread로만 읽기)
• admin([childId]/page.tsx)의 `Ctx` 렌더가 쓰는 context 키와 충돌하지 않도록 altLetter는 별도 네임스페이스 키만 읽는다

• 아린 Letter B 발행됨 → pickAltLetter(ctx) = {letter:'...', oneliner:'...', mirror:'...'} 반환 → 비교 카드 렌더
• 다른 자녀(altLetter 없음) → null → 단일 카드만(F-03이 두 번째 카드 스킵)
• 크론 부분 실패로 altLetter.letter=''만 있음 → null(빈 카드 방지)

• lib/altLetter.ts가 순수 함수(no I/O)로 단독 테스트 가능
• npm test 그린(prebuild 게이트)
• Letter A(v2 메인 letter/oneliner)는 이 함수와 무관 — A 무변경 확인
• 17 케이스 전부 통과

✅F-02 · 홈 coach_letters select에 context 추가 + altLetter 상태코드 코드 · 1h

• app/page.tsx 313행 `select('letter,oneliner,source_hash')` → `select('letter,oneliner,source_hash,context')`
• app/page.tsx 329행·337행 폴백 select에도 `,context` 추가(3경로 일관)
• 신규 상태: `const [altB, setAltB] = useState<AltLetter | null>(null)`(F-01 타입 import)
• cached/gen/prevL 분기에서 `setAltB(pickAltLetter(row.context))` 호출 — 표시 중인 편지의 context 기준
• 자녀 전환 race 가드(기존 `if (cancelled) return` 패턴) 안에서 setAltB도 가드 — 교차오염 방지(615행 주석 패턴 준수)
• 자녀 전환 시 altB 리셋: selectedId effect 진입부에서 `setAltB(null)`(기존 상태 리셋 컨벤션 따름)

• 아린 오늘 편지 cached → context.altLetter 파싱 → altB 세팅 → F-03이 두 번째 카드 렌더
• 다른 자녀 → context.altLetter 없음 → altB=null → 단일 카드
• 크론 폴백(api/cron/coach 재호출) 후 gen.context에서 altB 세팅

• coach_letters select 3경로에 context 추가
• altB 상태가 표시 편지 context 기준으로 세팅
• 자녀 전환 시 altB null 리셋 + cancelled 가드
• npm test 그린
• Letter A 표시 로직 무변경(대조군 보존)

✅F-03 · CompareLetterCard 두 카드 나란히 렌더 컴포넌트UI 코드 · 2h

• 신규 `web/components/CompareLetterCard.tsx`, `'use client'`(app/page.tsx와 동일 디렉티브)
• node_modules/next/dist/docs/01-app 읽고 클라 컴포넌트/props 규약 확인 후 작성(AGENTS.md 경고 준수)
• props: `{ letterA: string; onelinerA: string; altB: AltLetter | null; letterDate: string; childId: string | null; isMockup: boolean }`
• 두 카드 = 기존 코치 카드 스타일(background linear-gradient(135deg,#FFF8E1,#FFECB3), border 1.5px solid #F9A825) 재사용, 각 카드 상단에 라벨 배지: A='기존'(중립색)·B='새 설계'(강조색 #16A085)
• altB가 null이면 B 카드 영역 미렌더(`{altB && (...)}`) — 다른 자녀 단일 카드 무영향
• B 카드 본문 = altB.letter, oneliner = altB.oneliner, mirror 있으면 작은 회색 줄로 표기(어드민 검증 보조)
• 두 카드 모두 fmtLetterDate(letterDate) 날짜 라벨 — A/B 같은 날짜
• 피드백 버튼(F-04)은 각 카드 하단에 variant 구분해 배치(props로 onFeedback(variant, rating) 받음)

• 아린: A 카드(기존 v2) + B 카드(새 설계) 세로로 나란히, 라벨로 구분
• 다른 자녀: altB=null → A 카드만(기존 화면과 픽셀 동일)
• mockup(비로그인/3일 미만): altB=null → 기존 예시 카드 그대로

• node_modules/next/dist/docs/01-app 읽고 클라 컴포넌트 규약 준수
• CompareLetterCard가 altB 유무로 1카드/2카드 분기
• 기존 코치 카드 스타일 재사용(시각 일관)
• 렌더 테스트 8 통과(@testing-library/react 또는 기존 tests 패턴)
• npm test 그린

✅F-04 · 피드백 variant 컬럼 SQL + 유니크 재정의SQL SQL · 0.5h

• 신규 `web/sql/2026-06-13_letter_feedback_variant.sql`
• `alter table public.letter_feedback add column if not exists variant text not null default 'A' check (variant in ('A','B'))`
• 기존 unique(child_id,letter_date) 드롭 후 `unique (child_id, letter_date, variant)` 재생성 — 기존 제약명 확인 후 drop constraint(없으면 if exists 가드)
• RLS 정책 lf_owner는 그대로(parent_id=auth.uid()) — variant 추가가 정책에 영향 없음 확인
• 인덱스 lf_child_date(child_id, letter_date desc) 유지
• 기존 행 백필 불필요(default 'A'가 자동 적용)

• 아린 B 카드 👍 → variant='B'로 별도 행 insert(A 행과 공존)
• 다른 자녀 단일 카드 👍 → variant='A'(기본값) → 기존과 동일 동작
• 같은 날 B 카드 재투표 → onConflict(child_id,letter_date,variant)로 덮어쓰기

• SQL 파일 작성 + 이사님 실행 확인(실행 전 F-05 진행 금지)
• variant 기본 'A'로 기존 단일 카드 피드백 무변경
• 유니크가 (child_id,letter_date,variant)로 재정의
• RLS·인덱스 보존 확인

✅F-05 · variant별 피드백 upsert 배선 + 1탭 UI 상태코드 코드 · 1.5h

• app/page.tsx letterFb 단일 상태 → `const [letterFb, setLetterFb] = useState<{A: string|null; B: string|null}>({A:null,B:null})`
• upsert 호출(602행)을 `onFeedback(variant, rating)` 핸들러로 추출: `supabase.from('letter_feedback').upsert({ child_id, parent_id, letter_date, variant, rating }, { onConflict: 'child_id,letter_date,variant' })`
• CompareLetterCard에 onFeedback·feedbackState props 전달, 각 카드가 자기 variant의 선택 칩 하이라이트(기존 #F9A825 active 스타일 재사용)
• 기존 letter_feedback 로드(있으면 초기 선택 표시) — variant까지 select해 {A,B}로 매핑
• 낙관적 업데이트: setLetterFb로 즉시 칩 하이라이트 후 upsert(기존 패턴 동일)
• altB=null인 자녀는 B 핸들러 미노출(A만 — 기존과 동일)

• 아린 A 카드 👍 → variant='A' 행 / B 카드 🔁 → variant='B' 행(두 표 독립)
• B가 어드민 피드백에서 이기는지 측정(F-06 집계의 데이터 소스)
• 다른 자녀 단일 카드 👍 → variant='A'(기존 흐름 그대로)

• letterFb 상태가 {A,B} 구조
• upsert가 variant + onConflict 3키
• altB null 자녀는 B 경로 미노출(무영향)
• F-04 SQL 실행 확인 후 진행
• npm test 그린

✅F-06 · 홈 카드 영역에 CompareLetterCard 통합 + 기존 카드 치환UI 코드 · 1.5h

• app/page.tsx 582행 `{(isMockup || aiLetter) && (...)}` 블록 내부에서 실데이터 분기를 CompareLetterCard로 위임
• CompareLetterCard에 letterA=aiLetter, onelinerA=aiOneliner, altB, letterDate, childId, isMockup 전달
• mockup·과거폴백·지난편지(pastLetters)·리텐션 멘트는 기존 JSX 그대로(컴포넌트 외부 또는 내부 폴백 — 픽셀 동일 유지)
• altB=null이면 CompareLetterCard가 기존 단일 카드와 시각적으로 동일하게 렌더(F-03 보장)
• 빌드/타입 통과: 기존 import·상태(letterFb 등 F-05 변경분) 정합

• 아린 로그인 → 두 카드(기존/새 설계) + 피드백 + 지난편지 + 리텐션 멘트
• 다른 자녀 로그인 → 단일 카드(기존과 픽셀 동일)
• 비로그인/3일 미만 → 기존 예시 카드 그대로(altB 무관)

• 기존 단일 카드를 CompareLetterCard로 치환하되 altB null·mockup 시 픽셀 동일
• 지난편지·리텐션·예시 카드 보존(과한 변경 금지)
• tsc·build 그린·npm test 그린
• 다른 자녀 무영향 회귀 통과

✅F-07 · 어드민 [childId] A/B 피드백 분리 집계UI 코드 · 1h

• app/admin/[childId]/page.tsx 109행 `select('rating')` → `select('rating,variant')`
• 집계를 `fbA={up,down,repeat}`·`fbB={up,down,repeat}`로 분리(variant ?? 'A')
• 상단 자가진단 영역(160행 부근) 아래에 A/B 비교 줄 추가: 'A 👍N 👎N 🔁N · B 👍N 👎N 🔁N' + B가 up 우세·repeat 열세면 강조
• altLetter 발행 자녀(아린)만 B 카운트 표기, 그 외 기존 단일 fb 위젯 유지
• letterSimilarity 자가진단(119~132행)은 메인 letter(=A) 기준 그대로 — B는 별도 표기만(과한 변경 금지)

• 이사님이 어드민 아린 페이지에서 A vs B 피드백 누적 비교 → 승격 결정
• B가 👍 우세 + 🔁 열세 → 전 자녀 승격 신호
• 다른 자녀 → B 카운트 0/미표기, 기존 위젯 그대로

• 어드민에서 A/B 피드백 분리 카운트 노출
• 옛 행 variant='A' 처리(F-04 default 정합)
• 기존 자가진단·fb 위젯 보존(과한 변경 금지)
• npm test 그린

✅F-08 · E2E 회귀: 다른 자녀 단일 카드 무영향 검증테스트 테스트 · 0.5h

• tests/compare-card.test.tsx에 통합 시나리오 추가(기존 vitest + testing-library 패턴)
• 시나리오 1: altB=null 자녀 렌더 → 카드 1개, '새 설계' 배지 0, 피드백 버튼 3개(A만)
• 시나리오 2: altB 있는 아린 → 카드 2개, 피드백 6개(A 3 + B 3)
• 시나리오 3: pickAltLetter 회귀 — context.altLetter 없는 6가지 입력(null/undefined/빈letter/비객체 등 F-01 케이스) → 전부 단일 카드
• reexposure/replay 류 기존 테스트와 동일하게 prebuild 게이트에 포함

• 전 자녀 승격 전, 다른 자녀가 실수로 두 카드 보이는 회귀를 CI가 차단
• altLetter 스키마 오타로 카드가 안 뜨거나 빈 카드 뜨는 회귀 차단

• 다른 자녀 무영향 회귀가 CI(prebuild)에 고정
• Letter A가 항상 v2 메인 letter임을 단언
• 5 케이스 통과·npm test 그린

✅G-01 · letter_feedback.variant 컬럼 + compare_votes 테이블 SQLSQL SQL · 0.5h

• web/sql/2026-06-14_letter_feedback_variant.sql 신규. 멱등(if not exists / add column if not exists)
• letter_feedback에 variant text not null default 'A' check (variant in ('A','B')) 추가 — 기존 부모 피드백(메인 letter=A)은 default로 'A' 자동 매핑
• 기존 unique(child_id,letter_date) 제약을 unique(child_id,letter_date,variant)로 교체(부모가 A·B 둘 다 평가 가능). 제약명 drop/add 또는 새 인덱스 — 실행 전 기존 제약명 확인(점심 사고 교훈: SQL 실행확인 없이 다음 단계 금지)
• compare_votes 신설: id uuid pk · admin_id uuid not null · child_id uuid not null references children(id) on delete cascade · vote_date date not null · winner text not null check (winner in ('A','B','tie')) · note text · created_at timestamptz default now() · unique(admin_id,child_id,vote_date)(이사님 하루 1표 덮어쓰기)
• compare_votes RLS enable + policy: admin만(admin_id=auth.uid()). 어드민 페이지는 service_role 읽기라 RLS는 쓰기 보호용
• index cv_child_date on compare_votes(child_id, vote_date desc)

• psql/Supabase SQL editor에서 실행 → letter_feedback.variant 컬럼 존재·compare_votes 테이블 존재 확인
• 기존 letter_feedback 행 SELECT 시 variant='A'로 채워져 있음(NOT NULL 위반 없음)

• Supabase에서 실제 실행 확인(SELECT로 variant·compare_votes 존재 검증) 후에만 의존 원자 진행(점심 사고 교훈)
• 기존 부모 피드백 RLS·동작 무영향(variant default 'A')
• 파일 멱등 재실행 가능

✅G-02 · compareVote.ts — 승자 판정 순수함수(선호율·반복신고율)코드 코드 · 1.5h

• web/lib/compareVote.ts 신규. lib/coach.ts·coachDaily.ts처럼 순수함수 모듈 컨벤션
• type VariantTally = { up: number; down: number; repeat: number }; type CompareInput = { A: VariantTally; B: VariantTally; votes: Array<{ winner: 'A'|'B'|'tie' }> }
• scoreVariant(t: VariantTally): number — 가중 점수 up*2 - down*1 - repeat*1.5(반복신고를 별로보다 무겁게: v3 수렴이 핵심 결함). 표본 0이면 0
• repeatRate(t: VariantTally): number — repeat / (up+down+repeat), 분모 0이면 0
• decideWinner(input: CompareInput): { winner: 'A'|'B'|'tie'; reason: string; aScore: number; bScore: number; voteWinner: 'A'|'B'|'tie'|null; confidence: 'low'|'mid'|'high' } — ① 어드민 votes 다수결(voteWinner) 우선, ② 동률·무투표면 부모 점수 + 반복신고율 비교. confidence: 총표본<5=low·<15=mid·이상=high
• 요약 문자열 buildCompareSummary(input): 'B 우세 — 부모 👍 N:M·🔁 a%:b%·이사님 투표 X:Y' 형태(어드민·selfcheck alert 재사용)
• tie 임계: |aScore-bScore| 가 max(1, 총표본*0.1) 미만이면 tie(미세차 승자 단정 방지)

• 어드민 compare 위젯: 변형별 카운트 → decideWinner → 승자 배지·신뢰도
• selfcheck 크론: 'B가 A를 이기는지' alert 1줄 생성
• 무투표·표본0 콜드스타트: tie·low confidence로 안전 반환

• 순수함수 단독 테스트 18케이스 그린(불변 원칙②)
• vitest tests/compare-vote.test.ts 등록·prebuild 게이트 통과
• 어드민·selfcheck 양쪽에서 import해 재사용

✅G-03 · 부모 피드백 client upsert에 variant 전달코드 코드 · 0.5h

• app/page.tsx L602 supabase.from('letter_feedback').upsert(...) 에 variant: 'A' 추가
• onConflict: 'child_id,letter_date'를 'child_id,letter_date,variant'로 변경(G-01 신 제약 일치)
• 부모는 altLetter(B)를 보지 않으므로 'A' 고정 — 주석으로 명시(향후 B 노출 실험 시 prop으로 분기)
• 변형 미적용 기존 동작(👍/👎/🔁 토글·고마워요 멘트) 무변경

• 부모가 홈에서 편지에 👍 → letter_feedback에 variant='A'로 저장
• SQL 미실행 환경에서도 graceful(variant 컬럼 없으면 기존처럼 동작 — 단 G-01 선행 권장)

• 부모 피드백이 variant='A'로 저장됨을 라이브 확인
• 기존 UX 무변경(회귀 없음)
• G-01 SQL 실행 확인 후 배포

✅G-04 · 코칭 크론 — Letter B를 context.altLetter에 저장(아린 compare 모드)코드 코드 · 1h

• app/api/cron/coach/route.ts: finalCtx 객체(L698~713)에 ...(altLetterOut ? { altLetter: {...} } : {}) 병합
• compare 코호트 판정 = compareEnabled(process.env, cid) — 기존 v3Enabled 패턴 복제(COACH_COMPARE_CHILDREN 또는 기존 COACH_V3_CHILDREN 재활용). 인계서: compare 모드는 v3 순수 조립을 대체(아린은 더이상 v3 블록 조립 안 함)
• compare ON이면 v3 블록 조립 경로(v3Ctx) 분기 대신 Letter B 생성 경로 사용 — 단 본 원자는 '저장 자리'만, B 생성기 자체는 EPIC B~F 산출물(altLetterOut 주입 인터페이스만 정의)
• altLetter 스키마: { letter: string; oneliner: string|null; design: { unit?; mode?; materials: string[] }; mirror: string|null; verify: {ok:boolean}|null; model: string }
• 메인 upsert(L719) 그대로 — letter=A·oneliner=A·context=finalCtx(altLetter 포함). coach_letters 컬럼 변경 0
• compare OFF(타 자녀)는 altLetter 미생성·기존 경로 무변경(불변 원칙⑤ B만 적용·A 무변경)

• 아린 새벽 크론: A=composeLetter(v2) 저장 + context.altLetter=B 동봉
• 타 자녀: altLetter 없음, 기존 v2/v3 경로 그대로
• B 생성 실패: altLetter 생략(메인 A는 정상 발행 — fail-open)

• 아린 크론에서 context.altLetter 저장 라이브 확인(어드민 raw json)
• 타 자녀 경로 byte-동일 회귀 0(불변⑤ A 무변경)
• npm test 그린·tsc 0·build 0
• compareEnabled 순수함수 단독 테스트

✅G-05 · compareEnabled 코호트 게이트 순수함수코드 코드 · 0.3h

• web/lib/coachDaily.ts에 compareEnabled(env: { COACH_COMPARE?: string; COACH_COMPARE_CHILDREN?: string }, childId: string): boolean 추가(v3Enabled L20 복제)
• COACH_COMPARE==='1' → true · COACH_COMPARE_CHILDREN split(',').trim().filter.includes(childId)
• 주석: compare 모드는 아린 v3 순수 조립을 대체(인계서). 기존 COACH_V3_CHILDREN 재활용 시 route.ts에서 동일 id 전달도 허용

• env COACH_COMPARE_CHILDREN='43942d34-...' → 아린만 compare
• 미설정 → 전원 기존 경로(즉시 롤백=env 제거)

• 순수함수 단독 테스트 6케이스 그린
• v3Enabled와 키·동작 독립 확인
• prebuild 게이트 통과

✅G-06 · 어드민 쓰레드 — A/B 나란히 렌더 + 변형 라벨UI UI · 1.5h

• app/admin/[childId]/page.tsx 편지 렌더(L312~340): ev.data.context.altLetter 존재 시 두 버블 — A 버블 헤더에 칩 'A · v2 대조군', B 버블 헤더에 'B · 새설계' + altLetter.design.unit·mode·materials 요약
• B 버블에 기존 chip() 스타일 재사용(L318). B 검증결과(altLetter.verify.ok) 칩·model(sonnet) 칩
• altLetter 없으면 기존 단일 letter 버블 그대로(타 자녀 무영향)
• B 버블 아래 VoteButtons(G-08) 마운트 자리 — child_id·letter_date 전달
• Ctx(우리 판단)는 메인 context 그대로(altLetter.design은 B 버블 인라인)

• 아린 쓰레드: 6/14 칸에 A·B 두 버블 나란히 → 톤·재료·은유 직접 비교
• 타 자녀: 단일 편지(회귀 없음)
• altLetter.letter만 있고 oneliner 없는 경우도 안전 렌더

• 아린 쓰레드에서 A/B 나란히 노출 시각 확인(browse)
• 타 자녀 단일 렌더 회귀 0
• tsc 0·build 0·prebuild 게이트

✅G-07 · feedback/letter API — 변형별 부모 피드백 서버 라우트(옵션 채널)코드 코드 · 0.8h

• web/app/api/feedback/letter/route.ts 신규. POST 핸들러. AGENTS.md 경고대로 이 Next 라우트 규약 먼저 확인
• 입력 검증: rating in ['up','down','repeat']·variant in ['A','B'] 아니면 400
• createSupabaseServerAnon로 auth.getUser → 미인증 401. child_id가 본인 소유(children.parent_id=user.id) 확인 → 아니면 403
• letter_feedback upsert {child_id,parent_id,letter_date,rating,variant} onConflict 'child_id,letter_date,variant'
• 부수: 서버 경로라 RLS 우회 아님(anon 클라이언트 — 본인 행만). client upsert(G-03)와 공존(중복 채널이지만 서버 검증 강함)

• 향후 부모에게 B도 노출하는 실험 시 variant='B' 기록
• 서버 측에서 피드백 직후 집계 갱신 훅(확장)
• 비정상 variant·rating 차단

• 라우트 인증·소유·화이트리스트 검증 통과
• client upsert(G-03)와 공존·충돌 없음
• this Next 라우트 규약(AGENTS.md) 준수
• prebuild 게이트

✅G-08 · VoteButtons — 이사님 A/B 일일 선호 투표 client 컴포넌트UI UI · 1h

• web/app/admin/compare/VoteButtons.tsx 신규(client). props: childId·voteDate
• createSupabaseBrowser(싱글톤·메모리 교훈) auth.getUser → admin_id
• 버튼 3종 [A 좋음][B 좋음][무승부] → supabase.from('compare_votes').upsert({admin_id,child_id,vote_date,winner},{onConflict:'admin_id,child_id,vote_date'})
• 선택 하이라이트·낙관적 상태. note 텍스트 입력 옵션(짧은 사유)
• RLS 정책(G-01 admin_id=auth.uid)로 보호 — 클라 직접 쓰기 안전

• 이사님 아린 6/14 비교 → 'B 좋음' 클릭 → compare_votes 기록
• 다음날 같은 날짜 재투표 → 덮어쓰기
• 무승부 선택 → winner='tie'

• 이사님 투표가 compare_votes에 저장됨 라이브 확인
• 하루 1표 덮어쓰기 동작
• createSupabaseBrowser 싱글톤 사용(세션 회전 교훈)

✅G-09 · /admin/compare — 승자 집계 위젯 페이지UI UI · 1.5h

• web/app/admin/compare/page.tsx 신규. isAdmin 게이트(app/admin/page.tsx 패턴)·service_role 읽기·dynamic=force-dynamic
• createSupabaseAdmin로 letter_feedback(child_id,rating,variant)·compare_votes(child_id,winner,vote_date)·children(nickname) 조회
• 자녀별: variant A/B로 {up,down,repeat} 집계 → compareVote.decideWinner → 승자 배지·신뢰도·buildCompareSummary
• 일자별 이사님 투표 타임라인(vote_date desc·winner)
• altLetter가 있는 날짜 수(B 발행 일수) 표시 — coach_letters context.altLetter not null count
• 테이블 미생성/컬럼 미적용 graceful(빈 패널)

• 이사님: compare 페이지에서 'B 우세·high confidence·👍 12:4' 확인 → 컷오버 결정
• B 미발행 콜드스타트: '데이터 부족' 안내
• compare 코호트 0명: 안내

• 승자 집계가 compareVote.decideWinner와 일치(어드민·로직 단일 소스)
• graceful degrade(테이블·컬럼 미적용)
• tsc 0·build 0·prebuild 게이트

✅G-10 · 어드민 사이드바에 'A/B 비교' 진입점 추가UI UI · 0.2h

• web/app/admin/layout.tsx(AdminSidebar) 메뉴 배열에 { href: '/admin/compare', label: 'A/B 비교' } 추가 — 기존 항목과 동일 렌더 패턴
• 아이콘/이모지 컨벤션 따름(⚖️ 등)

• 이사님: 어드민 좌측 메뉴 → 'A/B 비교' → compare 페이지

• 진입점 노출·이동 확인
• 기존 사이드바 회귀 0

✅G-11 · selfcheck 크론 — 변형별 집계 + B vs A 승자 alert코드 코드 · 1h

• app/api/cron/coach-selfcheck/route.ts: letter_feedback select에 variant 추가, fbByChild를 { A:{up,down,repeat}, B:{...} } 구조로 집계
• compare_votes도 child_id별 조회(graceful try/catch — 테이블 없으면 생략)
• compareEnabled(process.env, cid) 자녀에 대해 compareVote.decideWinner → buildCompareSummary를 flags에 추가(예: 'A/B: B 우세 👍12:4·🔁0%:30%·투표 5:1')
• 기존 maxSim·onelDup·mirrorRate·fb.repeat·fb.down alert 로직 무변경(회귀)
• fb.repeat/down 기존 합산은 A·B 합으로 유지(전체 품질 경보 호환)

• 새벽 selfcheck: 아린 'B 우세' alert → cron_runs.meta.alerts
• compare 비대상 자녀: 기존 alert만(B 요약 없음)
• 피드백·투표 0: alert 미추가(노이즈 0)

• selfcheck가 변형별 집계·B승자 alert 기록 라이브 확인
• 기존 selfcheck alert 회귀 0
• compareVote 모듈 재사용(단일 소스)
• prebuild 게이트

✅G-12 · compare-vote.test.ts 통합 + 엣지 fixture 회귀테스트 테스트 · 0.5h

• web/tests/compare-vote.test.ts 신규(기존 tests/ 7파일 컨벤션·vitest)
• compareVote 18케이스 + compareEnabled 6케이스 구현
• fixture: '아린 6통 v3 수렴' 시나리오(B repeat 0·A repeat 3·이사님 votes B 우세) → winner='B' 고정 회귀
• 엣지 발견 시 fixture+테스트(red→green)+수정(불변 원칙③ 복리)

• 머지 전 npm test → compare 로직 그린
• 엣지(미세차·표본0·음수) 회귀 영구 보호

• tests/ 총 케이스 +24 이상, 전체 그린
• prebuild 게이트에서 실행됨
• 엣지 fixture 회귀 영구화(불변③)

✅H-01 · adversarial fixture — 괴식/OK 조합 골든 셋(comboGolden.json)테스트 테스트 · 0.75h

• 신규 `web/tests/fixtures/comboGolden.json` = {block:[...], ok:[...]} 배열. 각 항목 {dish, ingredient, matrixScore, pairBasis, expect}.
• block 케이스(실측): {dish:'미역국', ingredient:'당근'} — kit-dish-matrix.json scores['미역'].당근=1(낮음→금지). 한국 미역국엔 당근 안 넣음(브리프 A 실증).
• ok 케이스(실측): {dish:'볶음밥', ingredient:'당근', score:3}·{dish:'카레', ingredient:'당근', score:3}. scores['볶음밥'].당근=3·scores['카레'].당근=3 확인됨.
• pair-fallback 케이스: {dish:'짜파게티', ingredient:'당근'} — kit-dish-matrix.json에 '짜파게티' dish 키 없음(확인됨) → food-graph.json pair 엣지로 폴백 판정해야 함을 표기(via:'pair').
• 각 항목에 source 주석('kit-dish-matrix.json scores["미역"]["당근"]=1') — 데이터 드리프트 시 추적 가능하게.
• fixture 로더는 require/import JSON(기존 synthetic-families.json·real-arin.json import 패턴 답습).

• A-EPIC 조합 정합 검증기가 바뀌어도 동일 fixture로 회귀 측정
• matrix/그래프 데이터가 재생성되어 점수가 변하면 H-02 테스트가 빨개져 드리프트를 조기 포착

• fixture가 import되어 H-02 테스트에서 로드됨
• 모든 점수가 lib/kit-dish-matrix.json·lib/food-graph.json 실값과 일치(추측 0)
• npm test 그린(prebuild 게이트)

✅H-02 · 괴식 조합 적대 테스트 — comboFit 검증기(coach-materials.test.ts)테스트 테스트 · 1h

• 신규 `web/tests/coach-materials.test.ts`. A-EPIC 조합 정합 함수(예 `comboFit(dish, ingredient)`→{ok:boolean, via:'matrix'|'pair'|null, score:number}, 실제 export명은 A-EPIC 확정값 사용 — TBD(A-EPIC export명 확인 필요))를 import.
• H-01 comboGolden.json을 `it.each`로 돌려 block→ok=false, ok→ok=true 단언.
• 임계 검증: kit-dish-matrix.json scores[dish][ingredient]를 직접 읽어 score>=2면 ok, <2면 block이 되는지 경계값(미역국 당근=1 block / 볶음밥 당근=3 ok)으로 핀.
• pair 폴백: 짜파게티(matrix 키 없음)는 foodGraph.neighborsOf('당근')의 pair 엣지로 판정 — pair 존재 시 ok, 없으면 block.
• 오탐방지: 명백한 정합 조합(볶음밥+당근·비빔밥+당근 등 score≥2)을 block하지 않음을 다수 케이스로.
• 검증기가 LLM 후보를 거르는 통합 가정: pickFoodReco/buildMealMirror가 내놓은 dish×ingredient 쌍을 comboFit로 사전 필터함을 가정(B-EPIC 배선).

• 미역국+당근을 추천 후보에서 제거
• 볶음밥+당근·카레+당근은 후보로 통과
• matrix에 없는 dish는 food-graph pair로 안전 판정 또는 보수적 차단