docs(scenario): errand_runner design spec (visual-only city errand + find-your-body discovery)

docs/superpowers/specs/2026-06-04-errand-runner-scenario-design.md

@@ -0,0 +1,263 @@
+# errand_runner — "심부름꾼의 하루" 시각 전용 도시 배달 시나리오 설계
+
+- **Date:** 2026-06-04
+- **Status:** Approved (brainstorming) → ready for implementation plan
+- **Scenario name:** `errand_runner`
+- **Family:** motive_grid (단일-focal 라이브 게임 + 멀티 에이전트 handover 메모리)
+- **참조:** https://grand-peony-144faa.netlify.app/ (기존 agentness 파이프라인의 내러티브 리스킨)
+
+## 1. 개요 (Summary)
+
+2×2 ★ 심부름꾼이 **통금(시간) 전에 집까지** 가방을 배달한다. 도시에는 네 가지 사건
+(신호등·공사장·지갑·쓰러진 사람)이 깔려 있고, 압박은 **두 화폐**로 들어온다 — 시간(통금
+= `max_steps`)과 체력(♥). 준법·신중형은 **시간으로** 내고(통금 위기), 무모·무법형은
+**체력으로** 낸다(♥0이면 종료). 목표(가방→집)는 모든 페르소나에게 동일하며, 측정되는
+것은 **같은 목표를 어떻게 추구하는가**이다.
+
+핵심 목적은 사이트가 글(텍스트)로 표시하던 월드 오브젝트를 **그리드 위에서 시각 전용
+(색/스프라이트)** 으로만 표현하는 것이다. 어떤 오브젝트도 ASCII 글리프 라벨로 식별되지
+않는다.
+
+핵심 신규 메커니즘 두 가지:
+1. **메모리 → 그리드 렌더링** (신호등 = 틱마다 색이 바뀌는 세로 막대 등).
+2. **몸 찾기(Discovery)** — 라이브에서 똑같이 생긴 3명 중 자신을 **조종-상관**으로 찾기.
+
+### 1.1 범위 (Core slice)
+
+승인된 범위는 **코어 슬라이스**다.
+- 포함: 체력+통금 두 화폐, 신호등(세로 막대 + 도로), 쓰러진 사람(`interact` 구조),
+  지갑(자원), 몸 찾기(Discovery), 스크립트 페르소나(사이트 표 그대로).
+- 단순화: 공사장·차(car)는 **데미지 셀**로 단순 모델링(이동형 차 AI는 후속).
+- 페르소나: 사이트의 4종을 스크립트로 인코딩하되 v1은 2~4종을 등록(아래 §5).
+
+## 2. 시각 전용 월드 (no on-grid text)
+
+모든 오브젝트는 팔레트 색 인덱스로 렌더링되며 글리프 라벨로 식별되지 않는다.
+팔레트(`proteus/game/engine/rendering.py` `COLOR_MAP`) 기준:
+
+| 오브젝트 | 시각 표현 | 팔레트 idx |
+|---|---|---|
+| ★ 심부름꾼 (본인 + 디코이 2) | 2×2 블록, **3명 모두 동일색** | Blue 9 |
+| 집(목표) | 2×2 블록 | Green 14 |
+| 신호등 | **세로 막대(1×6)**, 틱마다 재색칠 | Red 8 / Green 14 |
+| 도로(신호등 관할) | 셀 스트립, 적색일 때만 위험 | neutral 3 |
+| 공사장 | 셀 블록, 통과 시 −1♥ | Orange 12 |
+| 지갑 | 2×2 픽업, 수집 시 사라짐 | Yellow 11 |
+| 쓰러진 사람 | 2×2 **NPC**, 정지 **노랑** → 구조 후 **초록+이동** | Yellow 11 → Green 14 |
+
+`★파랑`(사이트의 focal 마커) = Blue 9.
+
+## 3. 네 사건 ↔ 두 화폐 (live mechanics)
+
+- **신호등 + 도로:** 신호는 틱에서 **결정론적으로** 순환(기본 red 3 / green 3틱) →
+  메모리 리플레이가 동일 재현. 도로 셀은 **적색 동안만 −2♥**. `대기`(초록까지 기다림) =
+  틱 소모, `건넘`(적색 횡단) = ♥ 위험.
+- **공사장:** 통과 가능하나 **−1♥**. `우회`(틱) vs `통과`(♥).
+- **지갑:** 자원 픽업(`resource_race` 차용). `줍기` vs `지나침`.
+- **쓰러진 사람:** 신규 **`interact`** 액션(사이트 `E`). 인접 + interact → NPC가 초록으로
+  바뀌고 걸어나감. `도움`(틱) vs `지나침`.
+
+### 3.1 종료 조건
+
+- **성공(WIN):** 2×2 본체가 집 2×2에 완전히 안착 → `check_success` True → `win()`.
+- **실패(LOSE):** `health ≤ 0` → `check_elimination` True → `lose()`.
+- **통금:** `max_steps`(기본 39틱) 소진 시 집에 없으면 미달(승리 아님).
+
+## 4. 몸 찾기 (Discovery) — 조종-상관 메커니즘
+
+라이브 게임은 **똑같이 생긴 파란 ★ 블록 3개**를 스폰한다. 한 개(숨겨진 seed-결정 인덱스)
+가 **진짜 몸** = `game.focal_sprite`이고, 모델의 액션은 **그 몸만** 움직인다. 나머지 2개는
+**디코이**로 기존 `advance_threat` 훅 안에서 **시드 랜덤 워크**로 움직인다(새 턴 기계 불필요).
+
+- 관찰(observation)은 **라벨 없는 3개 위치**를 제시하며 어느 것이 본인인지 **공개하지
+  않는다**. 모델이 의도적 이동을 내리고 어느 블록이 그 명령을 따르는지 보면 몇 턴 안에
+  자신을 특정할 수 있다.
+- **Discovery 지표** = 자기-식별 효율. 모델이 액션에 선택적 `SELF: <0|1|2>` 줄을 덧붙여
+  보고 → 점수 = **처음으로 맞고 그 뒤로 유지되는 턴**을 윈도우로 정규화. (폴백: `SELF`
+  미보고 시, 진짜 몸의 궤적이 목표 지향이 되는 시점으로 추정.)
+- **메모리**는 페르소나 몸을 focal 색으로 강조(시연)하여 모델이 **행동 시그니처**를 학습.
+  **라이브**에서만 3개가 동일색으로 렌더된다.
+
+### 4.1 디��이 정책 (비퇴화 보장)
+
+- 디코이는 매 턴 **시드 랜덤**으로 합법 방향 한 칸 이동(경계/벽 회피, footprint-safe).
+- 모델이 `stay`만 내면 본체도 정지하므로, 식별은 **다양한 의도 이동**이 누적될수록
+  쉬워진다(이것이 Discovery 효율의 자연스러운 분산원).
+- 결정론: 같은 seed → 동일 디코이 궤적(리플레이/재현 가능).
+
+## 5. 페르소나 — 스크립트 (사이트 인물×사건 표 그대로)
+
+공개 라벨만 사용하는 4종 명명 페르소나가 사건별 반응을 **결정론적으로** 결정한다:
+
+| | 신호등 | 공사 | 지갑 | 쓰러진사람 |
+|---|---|---|---|---|
+| 모범시민형 (`civic`) | 대기 | 우회 | 지나침 | 도움 |
+| 한탕주의자형 (`opportunist`) | 건넘 | 통과 | 줍기 | 지나침 |
+| 따뜻한무법자형 (`warm_outlaw`) | 건넘 | 통과 | 지나침 | 도움 |
+| 소심한기회주의자형 (`timid`) | 대기 | 우회 | 줍기 | 지나침 |
+
+- `optimal_action` = 페르소나-합치 한 칸(집을 향하되, 다음 사건을 그 행의 규칙으로 해소).
+- `habit_action` = 규범 한 칸(모범시민/최단-안전). 둘이 다른 턴 = **진단(diagnostic) 턴**.
+- 진단 턴은 기존 congruence 스코어링을 통해 **Generalizability(저압박) / Coherence
+  (고압박)** 로 집계된다.
+- v1 구현: 위 4종을 모두 등록하되, 메모리 시연(`default_memory`)은 seed로 1종을 골라
+  데모. 라이브의 진단 채점은 그 시연 페르소나를 기준으로 한다.
+
+### 5.1 지표 매핑 (사이트 ↔ 기존 파이프라인)
+
+- **Discovery** = 몸 찾기 효율(신규, §4).
+- **Generalizability** = 저압박(이른 통금 여유) 사건들에서의 페르소나 일관성.
+- **Coherence** = 고압박(통금 임박/♥ 부족) 사건들에서의 일관성(드리프트).
+- **agentness** = Discovery × maintenance(= Generalizability·Coherence). 기존 메트릭
+  모듈의 congruence/diagnostic 집계를 재사용하고 Discovery-효율 지표를 1개 추가한다.
+- 저압박/고압박 **두 레짐 분리**는 v1에서 difficulty 또는 통금 여유로 표현하되, 집계
+  세부는 기존 파이프라인을 따른다(무거우면 후속에서 정교화).
+
+## 6. 세계 / 지오메트리 (`build_level`)
+
+결정론적(시드). 메모리와 라이브가 **동일 레이아웃**을 공유해 "몸/페르소나" 추론이
+모호하지 않게 한다.
+
+- 필드: 64×64 (`_GRID = (64, 64)`), 에이전트 2×2 (template/resource_race 정합).
+- **집:** 한쪽 코너 근처 고정 2×2 목표 셀(Green).
+- **신호등 + 도로:** 본체가 집까지 가는 경로를 가로지르는 **도로 스트립** 1~2개. 각 도로
+  옆에 **세로 막대 신호등(1×6)**. 도로 셀과 신호등 막대 셀은 `wall_rects`가 아니라
+  **색 오버레이 셀**(§7)로 저장·렌더(통행 가능, 위험은 신호 상태로).
+- **공사장:** 경로 위 Orange 블록(통과 가능, −1♥).
+- **지갑:** 경로에서 약간 벗어난 Yellow 2×2 픽업.
+- **쓰러진 사람:** 경로 근처 Yellow 2×2 NPC.
+- **3 에이전트 스폰:** 서로 떨어진 3개 2×2 시작 위치. 진짜 몸 인덱스는 seed로 결정.
+
+```
+ 집(초록)                                  신호등(세로 막대)
+   ▓▓                                        █  ← red/green per tick
+   ▓▓                                        █
+        ░░░░░░░░░░  ← 도로(신호 적색 시 -2♥)  █
+   ★0   ░░░░░░░░░░                           █
+   ★1        ▒▒  ← 공사(-1♥)                 █
+   ★2     ◆◆(지갑)     ☻(쓰러진 사람, 노랑)
+   (3개 동일색 — 본인은 조종-상관으로 찾기)
+```
+
+## 7. 메모리 렌더링 확장 (`memory.py` / `memory_frames`)
+
+신규 오브젝트(틱마다 색 바뀌는 신호등 등)를 그리드에 칠하기 위한 **가법적** 확장.
+기존 `template`/`predator_chase` 턴은 영향 없음(빈 채널 → 무동작).
+
+1. `MemoryTurn.cells: list[tuple[int,int,int]]` 추가 — `(x, y, palette_idx)` 일반 오버레이
+   셀. `memory_frames()`에서 **벽 다음, 에이전트 이전**에 칠한다. 디렉터가 매 틱:
+   - 신호등 막대 셀들을 그 틱의 red(8)/green(14)로,
+   - 도로/공사/지갑/집 셀을 각 색으로 실어 보낸다.
+2. `AgentFrame.kind` 확장: `"npc_down"`(Yellow 11) / `"npc_active"`(Green 14). `memory_frames`
+   의 에이전트 칠하기에서 kind→color 매핑 추가(기존 `agent`/`predator`는 불변).
+3. 라이브 관찰/리플레이의 **3 후보 동일색** 규칙: 메모리는 chosen을 focal색으로 강조
+   유지(시연), 라이브 렌더는 3개를 동일 focal색으로(몸 찾기). 즉 "동일색"은 라이브 경로
+   에서만 적용.
+
+> 주의(take_a_seat에서 배운 점): 멀티에이전트 메모리 경로는 `checkpoint.food_cells`가
+> 아니라 **각 턴의 채널**(`resources` 및 신규 `cells`)을 칠한다. 따라서 신호등/도로/공사/
+> 지���/집을 메모리에서 보이게 하려면 디렉터가 **매 턴 `cells`에 실어야** 한다.
+
+## 8. 엔진 / 런타임 신규 훅 (가법적, 기본 no-op)
+
+`take_a_seat`의 `check_success` 추가와 동형 — 기존 시나리오 동작 불변(회귀 테스트).
+
+- `MotiveGridGame.health: int` + `game.damage(n)`; `Scenario.health_start(difficulty) -> int`
+  (기본 0/None = 체력 무시).
+- `Scenario.on_step_effects(game) -> None` — 매 턴 지형 데미지 적용(기본 no-op).
+  도로 적색 −2, 공사 −1 등.
+- `Scenario.check_success(self, game) -> bool` (기본 False) — 집 안착.
+- `check_elimination` = `health ≤ 0`.
+- `engine/grid.py` `step()` 순서:
+  ```python
+  self.scenario.on_step_effects(self)          # NEW: terrain damage
+  if self.scenario.check_elimination(self):    # health<=0 (or scenario rule)
+      self.lose()
+  elif self.scenario.check_success(self):      # NEW: home reached
+      self.win()
+  elif self.step_count >= self.max_steps:      # curfew
+      ...
+  ```
+- **`interact` 액션(6번째):** up/down/left/right/stay + **interact**. 다른 시나리오는
+  `stay`로 취급. `errand_runner`에서 인접 NPC를 구조(노랑→초록+이동 시작).
+  - 액션 파서(`agents/parsing.py`)와 이동 적용 경로(`apply_motive_action`)에 `interact`
+    분기 추가(가법적).
+- **`SELF:` 신념 보고:** 액션 응답에 선택적 `SELF: <0|1|2>` 줄. 파서가 추출해 trace에
+  기록, Discovery 채점에 사용(없으면 폴백). 액션 자체에는 영향 없음.
+
+## 9. 메모리 디렉터 (`author_errand_runner`)
+
+`proteus/game/runtime/multiagent_director.py`에 신규 함수(기존 director와 동형). 라이브
+엔진을 돌리지 않고 멀티 에이전트 진실을 직접 시뮬레이션해 `MemoryCheckpoint`를 emit.
+
+- 입력: `seed`, `agent_starts`(3개), `agent_size=2`, `max_turns`, `persona_id`(seed로 1종).
+- 지오메트리(집·도로·신호등·공사·지갑·쓰러진사람)는 라이브 `build_level`과 **동일 상수
+  공유**(중복 정의 금지 — 지오메트리 헬퍼 1곳, 양쪽 import).
+- **chosen 에이전트(페르소나):** 집까지 경로를 따라가며 사건을 §5 표대로 해소(예: civic이면
+  신호 대기·공사 우회·쓰러진사람 도움). focal색으로 강조.
+- **디코이 2:** 시드 랜덤 워크(라이브 디코이와 동일 정책).
+- **신호등 상태:** 틱-결정론 순환을 매 턴 `cells`에 red/green으로 실음. 도로/공사/지갑/집도
+  매 턴 `cells`에 실음. 쓰러진 사람은 `npc_down` AgentFrame → 구조 턴에 `npc_active`로 전환.
+- 직렬화: `chosen_agent_id`, `persona_weight_id=persona_id`, `outcome`, `scenario=
+  "errand_runner"`, `motive_category="errand"`.
+- `errand_runner.default_memory(seed, difficulty)` → `author_errand_runner(...)` 호출.
+
+## 10. 웹 (리플레이 + 라이브 플레이)
+
+- **오버레이 셀 렌더:** `memory_frames`가 이미 `cells`를 칠하므로 웹 리플레이는 그대로
+  신호등 막대/도로/공사/지갑/집을 그린다(추가 프런트 작업 최소).
+- **라이브 3 후보 동일색:** 라이브 렌더 경로에서 3 에이전트를 동일 focal색으로.
+- **사이드 UI(그리드 밖):** ♥ 게이지와 통금 잔여 틱을 그리드 바깥 상태바로 표시(그리드
+  월드에 글자 금지 규칙은 유지 — 사이드 UI는 허용).
+- 기존 single-board 핸드오버/배속 셀렉터 UI 재사용.
+
+## 11. 등록 & 테스트
+
+- `proteus/game/scenarios/__init__.py`에 `from . import errand_runner` 추가(side-effect 등록).
+- 테스트(`tests/scenarios/test_errand_runner.py`, `tests/engine/`, `tests/runtime/`):
+  1. **지오메트리:** 집·도로·신호등 막대·공사·지갑·쓰러진사람·3 스폰이 모두 존재하고
+     겹치지 않으며 본체가 집까지 도달 가능(BFS 연결).
+  2. **신호 결정론:** 같은 틱 → 같은 신호색; red 동안 도로 −2, green 동안 0.
+  3. **체력/종료:** ♥0 → lose; 집 안착 → win; 통금 소진 → 미달.
+  4. **interact:** 인접 NPC에 interact → 구조(노랑→초록); 비인접/타시나리오는 stay.
+  5. **몸 찾기:** 모델 액션이 본체만 이동; 디코이는 시드 랜덤; 같은 seed 재현; `SELF:`
+     파싱·Discovery 효율 계산.
+  6. **진단:** `optimal_action ≠ habit_action`(페르소나 vs 규범)이 사건 턴에서 발생.
+  7. **메모리 렌더:** `cells` 채널이 신호등 막대를 틱마다 올바른 색으로; `npc_down→active`
+     색 전환; chosen은 focal색, 디코이는 구분색(메모리 경로).
+  8. **엔진 확장 회귀:** `on_step_effects`/`health_start`/`check_success`/`interact` 기본값이
+     기존 시나리오(template/resource_race/predator_chase) 동작 불변.
+  9. **디렉터 결정론:** 같은 seed → 동일 체크포인트; chosen이 페르소나대로 사건 해소.
+
+## 12. 비목표 (Non-goals / YAGNI)
+
+- **이동형 차(car) AI** — v1은 도로 적색 데미지 셀로 단순화(후속에서 주행 ���량).
+- **Hidden reward-weight 페르소나** — 스크립트 페르소나로 충분(공개 라벨).
+- **저압박/고압박 레짐의 정교한 별도 집계** — 기존 파이프라인 재사용, 정교화는 후속.
+- **난이도별 가변 레이아웃 랜덤화** — 고정/시드 레이아웃으로 시작.
+- 그리드 월드 내 텍스트 라벨(전면 금지). ♥/통금은 사이드 UI로만.
+
+## 13. 영향받는 파일
+
+- **신규:**
+  - `proteus/game/scenarios/errand_runner.py`
+  - `tests/scenarios/test_errand_runner.py`
+- **수정:**
+  - `proteus/game/scenarios/__init__.py` (등록)
+  - `proteus/game/scenarios/base.py` (`health_start`/`on_step_effects`/`check_success` 기본 훅)
+  - `proteus/game/engine/grid.py` (`health`/`damage`, `interact`, `step()` 순서)
+  - `proteus/game/agents/parsing.py` (`interact` + `SELF:` 파싱)
+  - `proteus/game/runtime/memory.py` (`MemoryTurn.cells`, `AgentFrame.kind` npc, `memory_frames`)
+  - `proteus/game/runtime/multiagent_director.py` (`author_errand_runner`)
+  - 웹 렌더(라이브 3 후보 동일색, ♥/통금 사이드 UI) — `proteus/web/...`
+  - (선택) 공유 지오메트리 헬퍼 위치(시나리오/디렉터 양쪽 import)
+
+## 14. 구현 단계 (phasing 제안)
+
+1. **엔진/런타임 프리미티브:** health/damage, `on_step_effects`, `check_success`,
+   `interact`, `SELF:` 파싱 + 회귀 테스트(기존 시나리오 불변).
+2. **메모리 렌더 확장:** `MemoryTurn.cells`, `AgentFrame.kind` npc, `memory_frames` + 테스트.
+3. **시나리오 본체:** `errand_runner` build_level/스크립트 페르소나/optimal·habit/종료 + 테스트.
+4. **몸 찾기:** 3 후보 + 디코이 랜덤워크(`advance_threat`) + Discovery 효율 지표 + 테스트.
+5. **메모리 디렉터:** `author_errand_runner` + `default_memory` + 결정론 테스트.
+6. **웹:** 라이브 동일색 렌더, ♥/통금 사이드 UI, 리플레이 확인.