# RALPLAN — 듀얼코치 단일 고객 유료 파일럿 (Bounded Planner Stage 8)

## Summary
Elevate the existing 최코치/Hermes coaching base into the smallest safe dual-coach pilot for **one external paid customer** (non-shop): KRW 150,000/month via bank transfer, a 12-week plan written up front, and only the first 4-week loop activated — adaptive customer check-in (60–90s), trainer 30-second session record, per-customer isolation, AI evidence draft → Richard review/edit/approve/send (zero auto-send), weekly summary, and KPI judgement (renewal, check-in ≥80%, satisfaction ≥8/10, operator time ≤60 min/week) — operated over Telegram plus a Richard-only private loopback web screen. Reuse existing registry/schedule/append-only store/grounding/Telegram routing. Explicitly no generic Hermes deployment, no global dashboard auth, no production-wide systemd rework, no browser framework, no multi-customer redesign.

## Principles
1. Human approval is absolute: AI drafts evidence; it never sends to the customer. Zero pre-approval sends.
2. Isolation is absolute: customer data/context/Telegram addresses never mix with personal coaching; append-only with `supersedes`, never overwrite.
3. Smallest safe surface: only the first-4-week daily/weekly loop runs; 12-week plan exists as grounding context, not active features.
4. Safety bundle gates activation: any unverified safety item = real customer stays disabled.
5. One KPI source of truth: renewal/check-in/satisfaction/operator-time judged from a single record origin.
6. Loopback-only operator web: 127.0.0.1 bind or SSH tunnel, Richard-only, no external exposure, no auth framework.
7. Medical boundary: pain/disorder/eating-risk/drug/extreme-manipulation signals stop normal feedback and escalate to human review + professional referral.

## Intent Diff (reconciliation with deep-interview spec)
- Spec Round 2 correction honored: 3-customer launch → **1 paid customer pilot**.
- Spec Round 4 acceptance honored: private web console is **in** first-pilot scope, but its core is strictly `evidence view → edit → approve → send`.
- Spec Rounds 10–11 closure honored: 12-week plan is written before start; only daily/weekly loop features activate in weeks 1–4.
- Lateral-panel guardrail honored: web must not become a separate product; no multi-customer/long-term features.
- All confirmed outcomes from the assignment are preserved verbatim in scope and acceptance criteria.

## Decision Drivers
- HANDOFF: registry empty (0 customers), intentionally disabled to prevent accidental customer messages; onboarding order (inactive draft → plan review → consent → validate → enable) already mandated.
- HANDOFF: past Telegram token exposure → rotation required before any customer activation.
- Spec technical context: `customer_reporting.py` lacks satisfaction/payment/renewal/operator-time measurement — the KPI gap is the main additive build.
- Spec technical context: current HTML is a static report/binder, not a live console — a new minimal loopback screen is required but must stay minimal.
- KPI conjunction (all four must pass) and ≤60 min/week operator budget push the design toward short confirmations on normal days and detailed evidence feedback only on change/problem days.

## Options
- **O1 Operator surface**: (a) minimal stdlib loopback HTTP screen bound to 127.0.0.1 with a single local token — **recommended**; (b) Telegram-only approval — rejected, spec requires the web screen; (c) framework dashboard with global auth — rejected, over-scope.
- **O2 Adaptive check-in**: (a) rule-based branching where anomaly fields (sleep/condition/performance drop) open only related follow-ups — **recommended**; (b) model-driven dynamic questioning — deferred (unpredictable latency/cost, risks 60–90s budget).
- **O3 KPI origin**: (a) extend `customer_reporting.py` into the single judgement source with append-only payment/satisfaction/operator-time events — **recommended**; (b) manual spreadsheet — rejected, violates single-source requirement.
- **O4 Draft approval storage**: (a) distinct events for AI draft / edited final / approval / send with timestamps — **recommended** (auditability is an acceptance criterion); (b) single overwritten field — rejected, violates append-only.

## In Scope
- One external paid customer: KRW 150k/month bank transfer, first 4-week pilot of a 12-week plan.
- Adaptive weekday customer check-in (60–90s; normal days short, anomaly days open only related follow-ups).
- Trainer 30-second session record (session done, performance, intensity vs plan, pain, operator notes) linked to same customer+date.
- AI evidence draft showing 12-week plan, recent records, trainer records, approved 최코치 knowledge, and judgement rationale; blocked when consent or safety signals are absent.
- Richard review/edit/approve/send on Telegram **and** a private loopback web screen; draft/final/edit history stored distinctly; 0 pre-approval sends.
- Weekly summary: check-in rate, key trends, keep-behaviors, change-behaviors, next decision point.
- KPI single source: scheduled vs completed check-ins, satisfaction, operator work time, first payment and actual renewal; 4-week judgement = conjunction of renewal done, check-in ≥80%, satisfaction ≥8/10, ≤60 min/week.
- Safety bundle: token rotation, mis-send prevention with test account, consent versioning + AI provider terms check (training use/retention/region/sub-processors), withdrawal/deletion/backup/log-retention procedures documented and tested, manual fallback mode without duplicate sends.
- Regression: personal check-in and Hermes wrapper suites stay green.

## Out of Scope
- Business registration, PG, auto-billing; multi-customer/multi-trainer/role accounts; B2B/SaaS; customer web portal; monthly auto-report delivery; auto knowledge refresh; AI auto-send; generic Hermes deployment; global dashboard auth; production-wide systemd changes; browser framework; shop DB/brand/payment/facility recruitment; any merge/replacement of the personal coaching flow.

## File-Level Changes (touch points only — reuse first, no redesign)
- `gateway/platforms/nutrition_coaching.py` — add adaptive check-in branching, trainer 30-second record flow, approval/send command path; keep owner-only draft request token and routing.
- `checkin_cli/customer_coaching.py` — extend schema: trainer session record, payment/renewal, satisfaction, operator-time events (append-only).
- `checkin_cli/customer_admin.py` — CLI for payment/satisfaction/operator-time recording; keep add/consent/enable gating and registry validation.
- `checkin_cli/customer_schedule.py` — weekday adaptive check-in + trainer record scheduling; keep claim/no-duplicate semantics.
- `checkin_cli/customer_grounding.py` — assemble evidence draft (plan, trends, trainer record, approved knowledge ≤5 excerpts, safety signals); hard-block on missing consent or safety signals.
- `checkin_cli/customer_reporting.py` — weekly summary + 4-week KPI judgement from the single record origin.
- New `checkin_cli/operator_console.py` — stdlib loopback HTTP screen (127.0.0.1, local token, draft queue, edit/approve/send); no framework, no external bind.
- `checkin_cli/store.py` — reuse as-is; no overwrite paths added.
- Docs: safety/ops runbook (withdrawal, deletion, backup, retention, manual fallback, provider-terms checklist) + one ADR.

## Sequencing & Dependencies
1. **Safety Gate 0 (blocks everything customer-facing)**: rotate Telegram token; `registry validate`; isolation audit; test-account mis-send prevention check; provider terms vs consent text alignment.
2. Schema/record extensions (trainer record, KPI events) + unit tests. Depends on Gate 0 for test fixtures only.
3. Adaptive check-in branching + trainer record flow in Telegram + tests (timing budget assertions).
4. Grounding evidence draft + draft/edit/approve/send audit events; verify 0 pre-approval sends.
5. Loopback operator console (minimal) wired to the same approve/send path as Telegram.
6. Weekly summary + KPI judgement report.
7. Runbook + manual fallback drill (model/web/Telegram outage → human operation, no duplicate sends on recovery).
8. End-to-end dry run with a test account; only after every safety acceptance criterion passes, follow the mandated onboarding order to enable the real customer.
Dependencies: 2→3,4; 4→5; 3,4→6; all →8. Personal-flow regression suite runs after every step.

## Acceptance Criteria (testable)
- AC1 Customer registered as inactive draft; independent storage root, Telegram address, consent record, and 12-week plan verified before `enable`; activation impossible otherwise.
- AC2 Token rotated; with a test account, cross-customer/personal mis-send count = 0 and permission boundaries verified.
- AC3 Weekday check-in completable in 60–90s; on normal days zero unnecessary detail questions open.
- AC4 On sleep/condition/performance anomalies, only related follow-up questions open.
- AC5 Trainer record (done, performance, intensity vs plan, pain, operator note) completable in ≤30s.
- AC6 Customer check-in and trainer record join on same customer+date; 0 records from other customers or personal data.
- AC7 Draft displays 12-week plan, recent records, trainer records, approved knowledge excerpts, and rationale; missing consent or safety signal → no draft.
- AC8 Richard can view evidence, edit, approve, send from the loopback web screen and Telegram.
- AC9 Pre-approval customer sends = 0; AI original, edited final, and edit history stored as distinct events.
- AC10 Normal days produce short confirmation; change/problem days produce detailed feedback.
- AC11 Weekly summary contains check-in rate, key trends, keep/change behaviors, next decision point.
- AC12 Single source yields scheduled denominator/completed count, satisfaction, all operator work time, first payment, actual renewal; 4-week judgement = logical AND of renewal, ≥80%, ≥8/10, ≤60 min/week.
- AC13 Withdrawal/deletion/backup/log-handling/retention procedures documented and tested.
- AC14 Provider training-use/retention/region/sub-processor terms checked and matched to consent version.
- AC15 Model/web/Telegram outage → manual human operation; recovery without duplicate sends.
- AC16 Personal check-in and Hermes regression suites all pass (baseline: 776 passed per HANDOFF).

## Focused Verification
- Re-run existing baselines after each step: profile tests (75), Telegram/Hermes wrapper tests (701), core wrapper tests (109); `compileall` on touched packages.
- New targeted tests: adaptive branching (normal vs anomaly), trainer record timing/fields, isolation join (zero cross-contamination), draft-block on missing consent/safety, approve/send audit (0 pre-approval sends), KPI judgement arithmetic incl. boundary values (79%/80%, 7.9/8.0, 60/61 min), loopback console refuses non-loopback bind.
- Manual drills: mis-send prevention with test account; outage→manual→recovery no-duplicate drill; withdrawal/deletion procedure walkthrough.
- Onboarding checklist execution (HANDOFF §6) as the final pre-activation gate.

## Risks & Mitigations
- R1 Token leak reuse → rotate first; assume old token compromised (HANDOFF §6).
- R2 Mis-send to wrong chat/topic → inactive-draft gating, test-account verification, claim checks before retry.
- R3 Auto-send regression → single send path behind explicit approval; audit events; tests assert 0 pre-approval sends.
- R4 Loopback screen exposure → 127.0.0.1-only bind test, local token, SSH tunnel doc; no external interface.
- R5 KPI source gaps → extend reporting first-class events, not ad-hoc notes; judgement test with boundary values.
- R6 Scope creep (multi-customer, dashboard) → out-of-scope list enforced at review; web core limited to evidence→edit→approve→send.
- R7 Provider terms mismatch → terms checklist tied to consent version before activation (AC14).
- R8 Operator time >60 min/week → short-confirmation default; time logged per task from day 1 so breaches surface weekly.
- R9 Safety signal missed → grounding hard-block + escalation path to human/professional referral; tested.

## Rollback
- Keep customer `enabled=false` until all safety ACs pass; disabling is a single registry state change.
- All customer data changes are append-only with `supersedes`, so any record-level change is reversible without data loss.
- Loopback console is additive; removing it leaves Telegram approval path intact.
- Personal coaching flow untouched; regression suites confirm no bleed.
- If pilot must halt mid-course: disable customer, stop schedules via existing claim semantics (no duplicate sends), retain/delete per documented retention procedure.

## ADR & Intent Reconciliation
- **ADR-1**: Adopt minimal stdlib loopback console over framework dashboard (O1a) — satisfies spec Round 4 with least surface; aligns with lateral-panel guardrail against a separate product.
- **ADR-2**: Rule-based adaptive check-in (O2a) — protects the 60–90s budget and operator-time KPI; model-driven questioning deferred.
- **ADR-3**: Single KPI origin inside `customer_reporting.py` (O3a) with append-only payment/satisfaction/operator-time events — required for the 4-week conjunction judgement.
- **ADR-4**: Distinct draft/final/approval audit events (O4a) — preserves append-only principle and AC9 auditability.
- **Reconciliation**: plan preserves every confirmed outcome (1 external paid customer, KRW 150k, 12-week plan, 4-week pilot, adaptive check-in, 30s trainer record, isolation, evidence draft, Richard review/edit/approve/send, Telegram + private loopback screen, weekly summary, four KPIs, safety + human approval) and excludes every named anti-scope item; no conflict with HANDOFF operating principles (SOUL.md remains supreme; customer auto-send remains forbidden).

## Handoff
- Executor: implement steps 2–7 strictly in sequence; do not touch files outside the touch-point list without escalation.
- Critic: review against AC1–AC16 and anti-scope list before any real-customer enable.
- Escalate to architect only if a touch point requires structural change beyond reuse.
- Final activation (step 8) is a human-gated checklist execution, not an autonomous action.