# 최코치 AI 코칭 시스템 — 인수인계서

이 문서는 구조·경계·현재 handoff 상태를 설명하는 **비실행 요약본**입니다. 파일럿 절차의 유일한 실행 정본은 [프로필 `PILOT_RUNBOOK.md`](file:///home/cube/.hermes/profiles/physique-coach/workspace/checkin_cli/PILOT_RUNBOOK.md)입니다.

- 정본 버전: `2026-07-26.23` (`dual-coach-gate-d-r23`)
- 정본 canonical contract SHA-256: `sha256:fc1fdfa0e228ad15458037b246245b540d5c5c27a67cd29ab0d1c834e7e2e952`
- Hash region: canonical profile `PILOT_RUNBOOK.md`의 `<!-- BEGIN CANONICAL EXECUTABLE CONTRACT -->`와 `<!-- END CANONICAL EXECUTABLE CONTRACT -->` 사이 UTF-8 바이트(마커 줄 제외, 본문 LF 포함)이며 마커 앞 metadata는 제외한다.
- 이 문서는 명령, REPL, 직접 registry/JSON 편집, provider 호출 예시를 담지 않습니다.

## 1. 한 줄 요약

Telegram 최코치는 **고객의 운동 일정과 매일의 몸 상태, 이전 조정 결과를 계속 이어서 보고 오늘 필요한 행동만 알려 주는 영양 코치**다. Richard 개인 피지크 체크인과 고객의 영양·생활습관 체크인은 분리한다. 고객 체크인은 고객 범위에 저장되고 운영자에게 완료 사실만 알린다. AI는 canonical 기록과 승인 artifact를 근거로 운영자 검토용 초안을 만들며, 운영자가 수정·승인·전송을 별도로 수행해야 고객에게 전달된다.

## 2. 제품 방향 정본

### 고객이 계속 사용할 이유

고객이 느껴야 하는 핵심 가치는 기능의 수가 아니라 다음 세 가지다.

1. **나를 기억한다:** 이전 약속, 실제 결과, 반복 패턴과 최근 조정에 대한 반응이 다음 코칭에 이어진다.
2. **오늘 할 일이 분명하다:** 결과는 `오늘 상태 → 이전 흐름과 비교 → 오늘 판단 → 오늘 할 일 1~3개 → 다음 확인 시점` 순서로 짧고 행동 가능하게 전달한다.
3. **변화를 먼저 알아챈다:** 수면 저하, 운동 수행 하락, 소화 문제, 일정과 식사의 불일치, 목표 범위를 벗어난 추세처럼 연결된 변화를 과장 없이 알려 준다.

고객이 체감해야 하는 반복은 `기록 → 이전 기록과 연결한 판단 → 오늘 행동 → 실제 결과 → 다음 판단`이다. 단순 알림이나 매일 새로운 조정이 아니라, 기록할수록 판단이 이어지고 좋아진다는 경험을 만든다.

### 고객 경험 원칙

- 고객 입력은 1분 안에 끝나는 아침 체크인을 목표로 한다.
- 정상적인 날은 짧게, 흐름이 달라진 날은 이유를 충분히 설명한다.
- 바꿀 이유가 없으면 `유지`도 명확한 코칭 결정으로 설명한다.
- 일간 코칭은 오늘의 행동에 집중하고, 주간 코칭은 지난 목표·실행·변화·이번 조정·다음 확인 기준을 연결한다.
- 전문 용어, 내부 상태명, 점수와 장부는 고객에게 노출하지 않는다.
- AI는 결정·수치·날짜·행동을 만들거나 바꾸지 않고, 코드가 잠근 판단을 이해하기 쉽게 설명한다.

### 단순한 운영 표면

내부 안전장치는 정교하게 유지하되 평상시 운영은 `체크인 → 검토 → 승인`으로 단순화한다.

- 고객: `오늘 체크인 → 제출 완료`
- 트레이너: `오늘 PT 기록 → 다음 일정 확인 → 저장`
- 운영자: `승인하고 보내기 / 내용 수정 / 보류`
- 내부 `revision`, `digest`, `epoch`, `reservation`, recovery 상태는 오류·감사 상세보기에서만 노출한다.
- Topic 59의 정상 검토는 고객 기록과의 연결성, 오늘 행동의 명확성, 근거보다 과한 단정이나 위험 조언의 부재만 확인한다.

### 유지·단순화·보류 기준

**반드시 유지한다.**

- 고객과 트레이너 기록의 연결
- 이전 조정과 실제 결과의 연결
- 일정 기반 운동일·휴식일 전략
- 위험 신호 우선 처리와 운영자 최종 승인
- 고객 격리, append-only 이력, 중복·오발송 방지

**사용자에게는 단순화한다.**

- 운영자에게 보이는 내부 상태와 버튼 수
- 고객 질문 수와 메시지 길이
- 기술적인 오류 표현
- 정상 흐름에서의 수동 단계

**실제 요구와 증거가 생기기 전에는 추가하지 않는다.**

- 새로운 대시보드와 상세 캘린더
- 더 많은 자동 알림과 고객 노출 점수
- 목적이 불분명한 AI 기능과 분석 항목
- 파일럿 고객이 요구하지 않은 운영 기능

새 기능은 `실제 고객 요구가 있는가`, `운영 시간을 줄이는가`, `코칭 정확도나 안전성을 직접 높이는가`, `기존 기능을 단순하게 개선하는 것으로 해결할 수 없는가`를 모두 검토한 뒤 추가한다.

### 파일럿 판단 지표

파일럿은 기능 수가 아니라 다음 값으로 제품 필요성과 운영 가능성을 판단한다.

- 고객 한 명당 운영자 일일 검토 시간
- 수정 없이 승인되는 초안 비율
- 고객 체크인 완료율
- 제안한 행동의 실천율
- 위험·충돌·보류 카드 발생률
- 중복·오발송 건수
- 고객이 코칭을 이해하고 필요하다고 느끼는 비율

**제품 결정 문장:** 내부 안전장치는 정교하게 유지하고, 고객 경험은 체크인과 오늘의 행동으로 단순하게 만든다.

## 3. 영구 운영 원칙

1. 고객·트레이너·운영자의 주소와 데이터는 exact triple 및 `(chat_id, topic_id)` 공간으로 분리한다.
2. 고객에게 AI 초안이나 자동 피드백을 직접 보내지 않는다. 전송은 최신 revision에 대한 운영자 승인 뒤 한 번만 가능하다.
3. 기록은 append-only이며 정정은 새 event와 `supersedes`로 남긴다.
4. 안전 신호·동의 부재·오래된 권한·손상된 장부·전송 불명은 fail closed한다. 의료 진단·약물/용량·극단적 조작 조언은 하지 않는다.
5. 공개 자료는 발견→검토 제안→Richard 승인→지식 반영 순서이며 자동 반영하지 않는다.
6. 28일 KST 파일럿 창은 갱신 결제로 연장되지 않는다. 29일째 자동 작업은 없다.
7. 실제 계정·토큰·고객 활성화·수동 Gate-D는 사람만 수행한다.

## 4. 현재 handoff 상태

- 개인 체크인, 고객/트레이너 라우팅, 고객별 계획·동의·스케줄·운영자 초안 구조는 profile과 gateway가 canonical 경계를 공유한다.
- 실제 고객 활성화와 adaptive customer delivery는 승인되지 않았고, 수동 Telegram Gate-D는 아직 수행하지 않은 상태로 취급한다.
- 자동화된 preflight와 P2–P6 barrier 증거는 수동 Telegram 증거 또는 real-customer rollout 승인으로 재사용하지 않는다.
- 최신 테스트 개수나 서비스 상태를 이 문서에 고정하지 않는다. release owner가 현재 실행 결과와 정본 SHA-256을 별도 private evidence에 남긴다.

## 5. 핵심 경계 지도

### 프로필과 데이터

- 프로필 지침과 안전/말투 규칙: `SOUL.md`
- 고객 등록·plan·동의·활성화 경계: profile workspace의 canonical customer modules
- 고객 canonical source: 고객 범위의 wizard EventStore
- adaptive projection/journal: 고객의 private `nutrition-plans` 아래에만 additive로 저장
- 공개 자료: profile knowledge layer의 승인된 doctrine와 source catalog

개별 customer registry, EventStore, adaptive journal, schedule ledger는 직접 편집하지 않는다. 장애·삭제·보존·백업은 owner/legal approval을 거친 정본 recovery 절차로만 처리한다.

### 개인·고객·트레이너 라우팅

Richard 개인 공간은 고객 공간과 별도다. 고객 공간은 exact customer triple만, 트레이너 공간은 등록된 exact trainer triple만 처리한다. 잘못된 user/topic/chat은 generic/model/media 경로로 흘러가지 않아야 한다.

## 6. Topic-59 adaptive 운영자 경계

Host-owned `AdaptiveOperatorService`가 Topic 59의 review 공간을 모든 Telegram update 종류보다 먼저 예약한다. 정확한 configured review full triple은 ingress 인증이고, canonical owner full triple은 lifecycle/audit actor다. 두 identity는 달라도 되며, 모든 mutation 직전에 owner/config/registry/consent/activation/source/artifact/epoch pins를 새로 확인한다.

운영자 메뉴는 `적응형 영양 검토`와 같은 처리기의 별칭으로 시작하고, live enabled eligible customer를 host가 선택한다. typed action과 persisted session/capability만 허용한다. raw destination/text/digest, generic append, REPL, direct registry enable은 생산 경로가 아니다.

Host coordinator의 production flow는 proposal 생성→note 수정 시 새 child revision→최신 revision 승인→epoch 기반 activation→persisted delivery enable/revoke→reservation→단일 provider call→receipt/audit→reconcile 순서다. `delivered`와 `sent_audited`가 함께 있어야 성공이다.

## 7. 전송·일정·재시작

Adaptive와 scheduled delivery 모두 reservation-first, provider-at-most-once다. 결과 불명과 receipt-present/audit-pending은 terminal no-retry다. receipt가 있으면 provider call 0으로 audit만 조정하며, 없으면 추측한 ID를 넣지 않는다.
Adaptive delivery's canonical durable rows are `reservation-started` (the receipt-free reservation row), `consumed`, `receipt-started` (the immutable provider receipt row), `delivered`, `audit_pending`, and `sent_audited`. `receipt-started` persists the result of the single provider call; it is not a second provider call or resend. P2 therefore has `reservation-started → consumed → receipt-started → delivered → sent_audited`; P4 has `reservation-started → consumed → receipt-started → delivered → audit_pending` before reconcile and adds `sent_audited` after reconcile.

Scheduled ledger는 immutable destination/body/day, reservation, receipt, state를 보존한다. cutover 시 구형 `.claim` tombstone을 먼저 durable하게 만들고 새 `prepared` row를 기록한다. tombstone/ledger pair가 맞지 않거나 startup fence가 `ready`가 아니면 scheduler는 전송하지 않는다. legacy claim은 보수적인 `unknown`으로 이관하고 구형 retry/release는 read-only 진단으로 남긴다.

재시작·rollback 순서는 scheduler/Gateway 중지→persisted delivery revoke→고객 disable→append-only 증거 보존→host recovery→journal/epoch/tombstone/fence 검증→trusted backup 또는 rollback 검토다. 수동 JSONL 자르기·덮어쓰기·blind retry는 금지한다.

## 8. Gate-D P2–P6 handoff 계약

각 시나리오는 fresh independent latest child revision이며 이전 revision을 재사용하지 않는다. 공통 fixture는 disposable isolated customer, 별도 bot, 서로 다른 operator/customer/trainer identity, current KST window, approved artifacts, canonical reconciliation, epoch active/delivery false, prior reservation 0이다.

- **P2:** `reservation-started → consumed → receipt-started → delivered → sent_audited` exactly 5 rows, provider total 1; a duplicate tap returns duplicate with no additional rows/provider call.
- **P3:** `reservation-started → consumed → delivery_unknown` exactly 3 rows, provider total 1; retry adds 0.
- **P4:** Before reconcile `reservation-started → consumed → receipt-started → delivered → audit_pending` exactly 5 rows; reconcile adds one `sent_audited` row and provider adds 0 calls.
- **P5:** reservation barrier; `reservation-started → delivery_unknown` exactly 2 rows (`delivery_revoked_after_reservation`), consumed/receipt/delivered/audit/provider 0.
- **P6:** reservation barrier; `reservation-started → delivery_unknown` exactly 2 rows (`owner_changed_after_reservation`), consumed/receipt/delivered/audit/provider 0. reservation 전 rotation은 `transition_aborted`.

P2 성공·중복, P3/P5/P6 unknown, P4 receipt/audit-pending의 정확한 한국어 화면 문구와 final cleanup은 정본의 P2–P6 표를 따른다. 각 행 뒤 delivery revoke와 terminal receipt를 남기고, 마지막에는 overlay rollback, disposable customer disable, scheduler/Gateway stop, immutable evidence 보존을 확인한다.

## 9. Read-only preflight와 human-only boundary

정본의 typed preflight는 config, full review triple, private mode/symlink, isolated test profile/bot, 세 identity, current KST window, approved artifacts, canonical reconciliation, schedule/transition ledgers, all delivery flags를 읽기만 검사한다. 반환은 boolean/count/digest/epoch뿐이다. 계정·토큰·고객·동의·artifact·activation·delivery·provider message를 만들지 않는다.

사람이 해야 하는 일은 다음과 같다.

- Telegram 테스트 계정·bot·group/topic와 provider/operator secret 준비
- 고객 동의와 private registration/activation checklist 승인
- 실제 Telegram 수동 Gate-D 리허설과 opaque evidence 수집
- real-customer activation/delivery와 최종 rollout 승인
- data-rights deletion, retention expiry, backup purge, provider-terms sign-off

자동 preflight와 P2–P6 결과를 manual Gate-D 완료로 표시하지 않는다. 현재 handoff의 안전한 결론은 **real customer disabled, live delivery 없음, manual Gate-D pending**이다.

## 10. 2026-07-29 현재 실제 인수인계 상태

### 사용자의 확정 의도

- 목적은 **Richard 개인 코칭 시스템에서 가상 고객과 테스트 전용 Telegram 공간으로 수동 검증한 뒤 사용하는 것**이다.
- Hermes 공식 프로젝트에 기능을 기여하거나 upstream에 병합하는 것은 목적이 아니다.
- 불필요한 재설계, 새 플러그인 개발, upstream 포팅, 대규모 구조 변경을 진행하지 않는다.
- 사용자는 개발자가 아니므로 다음 에이전트는 먼저 쉬운 한국어로 `왜 필요한지`, `무엇이 바뀌는지`, `지금 눌러도 되는지`를 짧게 설명한다.
- 명시적으로 요청받지 않은 주변 문제를 확대하지 않는다. 현재 목표는 기존 가상 고객의 테스트 준비 상태를 정상화하고 수동 Telegram 검증으로 넘기는 것이다.

### Hermes upstream 정리

- 잘못 생성했던 NousResearch upstream PR `#74072`는 2026-07-29에 **closed** 처리했다.
- 해당 PR은 최신 upstream보다 6,916 commits 뒤처진 구조에서 만들어졌고 `dirty`/non-mergeable 상태였으므로 배포 대상으로 사용하지 않는다.
- 이 프로젝트를 위해 Hermes 공식 저장소에 새 PR을 만들거나 merge/rebase/port하지 않는다.
- 공개 Hermes 저장소에 private Profile 코드, 고객 fixture, Telegram 주소, 승인 문서, 토큰 또는 테스트 증거를 올리지 않는다.
- 로컬 Hermes 작업트리의 무관한 기존 변경을 stash, reset, clean, revert 또는 commit하지 않는다.

## 11. 구현 및 Git 기준점

### Private Profile

- 저장소: `/home/cube/.hermes/profiles/physique-coach`
- private branch: `main`
- 제품화 commit: `57aaf75` (`Connect approved actions to daily coaching continuity`)
- 핵심 source:
  - `workspace/checkin_cli/checkin_cli/adaptive_nutrition.py`
  - `workspace/checkin_cli/checkin_cli/customer_coaching.py`
  - `workspace/checkin_cli/checkin_cli/customer_reporting.py`
- 일간 registered projection, 승인 행동 continuity/outcome, 주간 review source가 구현되어 있다.
- 기존 한국어 renderer와 canonical EventStore가 정본이다. 별도 AI memory DB나 copy engine을 만들지 않는다.

### Local/Fork Gateway

- 작업트리: `/home/cube/projects/richard/hermes-agent`
- branch: `feature/dual-coach-lifecycle`
- 제품화 commits:
  - `d9e03e938` (`Make daily coaching continuity safely publishable`)
  - `0dc0f228d` (`Preserve provider-zero retry semantics in production fixtures`)
- fork에는 push되어 있지만 upstream 병합 대상이 아니다.
- Topic 59 exact preview, immutable child reapproval, approve-and-send recovery, provider/publication at-most-once, preflight-vs-unknown 분류가 구현되어 있다.
- 실제 Telegram/provider 호출은 자동 검증에서 수행하지 않았다.

### 마지막 검증 증거

- Profile 제품화 대상: `302 passed`
- Gateway adaptive lifecycle 전체: `126 passed`
- Gateway 제품 lifecycle focused: `12 passed`
- exact compact card focused: `1 passed`
- 대상 `py_compile`, Ruff, `git diff --check`: 통과
- 전체 legacy Telegram/Nutrition 합본에서 관찰된 일부 실패는 기존 `dualcoachtest` import/fixture contamination 및 오래된 일정 fixture와 관련되어 있었다. focused live-profile 대상 결과와 혼동하지 않는다.
- 마지막 architecture review는 `CLEAR / APPROVE`, terminal Critic은 `OKAY`였다. 이는 구현 안전성 검토 결과이며 수동 Telegram Gate-D 완료를 뜻하지 않는다.

## 12. 가상 고객의 현재 상태

테스트 대상은 isolated profile `/home/cube/.hermes/profiles/dualcoachtest`의 `virtual_customer`다. 이 이름은 테스트용 opaque key이며 실제 고객이 아니다.

2026-07-29 typed read-only preflight에서 확인한 값:

- `profile_contained = true`
- `private_modes = true`
- `enabled_isolation = true`
- `identity_roles_distinct = true`
- `review_operator = true`
- `separate_bot = true`
- `current_kst_window = true`
- `canonical_reconciliation = true`
- `delivery_disabled = true`
- `schedule_fence / ledger / tombstones / transitions = true`
- canonical events / sequences: `104 / 104`
- source-day mappings: `44`
- source-day intents: `88`
- authority rows: `4`
- config epoch rows: `8`
- current feature epoch: `3`
- feature flags: `analytics_shadow=false`, `operator_candidates=false`, `activation=true`, `delivery=false`

중요한 현재 판정:

- activation receipt는 기존 registry drift 때문에 처음에는 stale/missing이었다.
- 2026-07-29 사용자의 확인 후 `disable_customer`와 guarded `activate_customer` typed API만 사용해 테스트 고객 activation receipt를 재발급했다.
- raw registry, JSONL, feature epoch, canonical event를 직접 편집하지 않았다.
- 재발급 뒤 typed preflight는 `activation_receipt = true`로 확인했다.
- 새 activation receipt 때문에 이전 adaptive registration 승인이 현재 authority와 더 이상 맞지 않아 `registration_missing` 상태다.
- 현재 preflight stop codes는 `feature_flags_enabled`, `registration_missing`이다.
- 고객 delivery는 계속 `false`이므로 현재 오발송 가능한 상태는 아니다.
- activation 재발급 직후 별도 `validate_committed_activation` 호출은 activation journal과 profile registry 불일치 오류를 냈지만, 후속 정본 preflight에서는 activation receipt를 유효하게 읽었다. 다음 에이전트는 이 차이를 무시하거나 raw 파일로 맞추지 말고 typed recovery/validation 경로의 일관성을 먼저 확인한다.

## 13. 다음 에이전트가 바로 수행할 단일 목표

**가상 고객의 adaptive registration과 승인 artifact를 새 activation receipt에 안전하게 다시 결속하고, 모든 정본 검사를 통과시킨 뒤 수동 Telegram 테스트 단계로 넘긴다.**

반드시 지킬 순서:

1. canonical profile `PILOT_RUNBOOK.md`의 현재 버전과 contract digest가 위 문서 상단의 pin과 일치하는지 읽기 전용으로 확인한다.
2. `audit_gate_d_preflight(profile_root, "virtual_customer")`를 다시 실행해 현재 stop codes와 bounded counts를 재확인한다.
3. `validate_committed_activation`과 preflight의 activation 판정 차이를 typed API 및 activation journal recovery 로직에서 조사한다.
4. 기존 adaptive registration을 raw JSONL에서 복사하거나 수정하지 않는다. 새 receipt에 기존 승인 내용을 재결속하는 공개 typed API가 있으면 그 API만 사용한다.
5. 지원되는 rebind/reapproval API가 없다면 product data를 우회 수정하지 말고 Profile source에 최소한의 fail-closed typed recovery API가 필요한지 판단한다. 새 API는 기존 입력·artifact digest·owner·receipt가 모두 정확할 때만 append-only child approval을 만들고 conflict 시 중단해야 한다.
6. policy, meal constraints, food catalog, registration input은 기존 승인된 의미를 바꾸지 않는다. 재승인은 새 activation authority에 대한 결속만 갱신해야 한다.
7. epoch `3`, canonical `104/104`, source-day mapping `44`, 기존 proposal/revision/history를 보존한다. synthetic history를 만들거나 revision을 초기화하지 않는다.
8. `activation=true`가 현재 stale proposal overlay인지, 수동 Telegram 테스트에 필요한 현재 lifecycle 상태인지 host의 typed lifecycle projection으로 판정한다. feature epoch 파일을 직접 고치지 않는다. rollback/revoke가 필요하면 기존 host action과 capability 경로만 사용한다.
9. 준비 후 read-only preflight와 focused tests를 다시 실행한다. false check가 남으면 Telegram 테스트를 시작하지 않는다.
10. 자동화가 계정·bot·Topic·provider를 조작하거나 메시지를 보내지 않는다. Telegram 수동 테스트는 Richard가 직접 수행한다.

## 14. 준비 완료의 정확한 기준

다음 조건을 모두 만족해야 Richard에게 `이제 테스트방에서 시작해도 됩니다`라고 말할 수 있다.

- activation receipt와 registry가 같은 current authority에 결속되어 있다.
- approved registration 및 policy/catalog/constraints artifacts가 새 receipt에 결속되고 stale하지 않다.
- canonical events와 sequence가 full equality 기준으로 일치한다.
- customer, trainer, review operator 공간이 exact triple로 분리되어 있다.
- 실제 고객 entry, 운영용 destination, 운영 provider credential이 없다.
- adaptive delivery는 테스트 시작 전 `false`다.
- schedule fence와 ledger가 ready이고 corrupt/torn/preparing 상태가 없다.
- preflight의 모든 필수 check가 true이며 `ready = true`다.
- focused Profile/Gateway tests와 exact preview/body pin 검증이 통과한다.
- 자동 provider/Telegram call count는 `0`이다.

## 15. Richard가 수행할 수동 Telegram 확인 순서

준비 완료 판정 뒤 Richard가 테스트 전용 bot과 테스트 전용 Topic 59에서 직접 확인한다.

1. Topic 59에서 `적응형 영양 검토`를 연다.
2. `가상 테스트 고객`을 선택한다.
3. 새 검토 카드를 생성한다.
4. 카드의 고객 전달 미리보기가 짧고 실제 고객용 문구인지 확인한다.
5. `내용 수정`을 실행해 immutable child revision과 재승인 요구를 확인한다.
6. `보류` 후 `검토 다시 시작`을 확인한다.
7. 최신 카드에서 `승인하고 보내기`를 한 번 실행한다.
8. 테스트 고객 Topic에 정확히 한 메시지만 도착하는지 확인한다.
9. 같은 버튼을 다시 눌러 provider call과 메시지가 추가되지 않는지 확인한다.
10. 결과 불명 또는 receipt/audit-pending 문구가 나오면 다시 보내지 않고 중단한다.

이 수동 단계에서는 테스트 전용 공간임을 Richard가 직접 확인한다. 자동 에이전트는 Confirm 클릭, delivery enable, provider 호출 또는 Telegram 메시지 발송을 대신하지 않는다.