oh-my-design-cli 0.1.2 → 1.0.0

package/skills/omd-harness/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: omd:harness
+description: "디자인 하네스 진입점. 사용자가 '디자인 하네스 돌려줘', '시니어 디자이너처럼 ~ 만들어줘', '/omd-harness <task>'를 호출하면 run 디렉토리를 부트스트랩하고 omd-master 오케스트레이터를 spawn해서 10-phase 파이프라인(Discovery / Asset / Research / IA / Wireframe / System / Components / AssetSourcing / Microcopy / Validation / Handoff)을 실행, 10 specialist를 dispatch해서 brief + DESIGN.md + wireframes + components + assets + persona-feedback 패키지를 emit합니다."
+---
+
+# omd:harness — Design Harness Entry
+
+이 스킬은 **omd-master 오케스트레이터**를 호출하는 단일 진입점이다. 본 스킬은 launcher + 사전체크 + run 디렉토리 부트스트랩 책임만 가지고, phase 로직은 `agents/omd-master.md`에 있다.
+
+CLI 의존 없음. 모든 부트스트랩은 Bash + Write 툴로 직접 실행한다.
+
+## 트리거
+
+- `/omd-harness <task>` 명시 호출
+- 사용자가 자연어로 "디자인 하네스 / 시니어 디자이너처럼 / 알아서 디자인" 요청
+
+## Step 0 — task 추출
+
+슬래시에 task 같이 적었으면 (`/omd-harness 물 음용 유도 메인 화면`) 그 자연어 부분이 task. 빈 슬래시면 한 번 묻기:
+
+```
+어떤 디자인 작업을 진행할까요?
+shape: "[도메인] + [톤/스타일] + [핵심 화면]" — 예: "토스 스타일 가족용 식단 앱 메인 화면"
+```
+
+## Step 1 — Subagent registration 사전체크 (CRITICAL)
+
+`omd-master` subagent가 이 세션에 dispatch 가능한지 verify. Agent tool의 사용 가능 subagent 목록에 `omd-master`가 있으면 진행. 없으면:
+
+```
+omd-master subagent가 이 세션에 등록되어 있지 않아요. Claude Code는 세션 시작 시점에만 .claude/agents/*.md를 로드합니다 — install-skills를 세션 띄운 후에 돌렸으면 이 케이스.
+
+해결 (가장 빠른 순서):
+1. 현재 세션에서 /agents 실행 — Claude Code가 .claude/agents/*.md 강제 재스캔. omd-* 8개가 목록에 나타나면 /omd-harness 재호출.
+2. 안 되면: Claude Code 앱 완전 종료 (Cmd+Q / 터미널 자체 quit) → 새 터미널 → claude 재실행 → /omd-harness <task> 재호출.
+```
+
+## Step 2 — Run 디렉토리 부트스트랩 (인라인 Bash)
+
+이전엔 `omd harness "<task>" --internal` CLI를 호출했지만 1.0.0부터는 스킬이 직접 한다. 결정론적 hard verify gate:
+
+### 2.1 기존 run 재사용 체크
+
+```bash
+ls -t .omd/runs 2>/dev/null | head -1
+```
+
+출력 있으면 그 디렉토리의 `task.md`를 Read해서 사용자 task와 의미적으로 일치하는지 확인. 일치하면 그 run 재사용 — Step 3으로 점프.
+
+### 2.2 신규 run 부트스트랩
+
+다음을 **반드시 정확히 이 순서로** Bash 툴로 실행:
+
+```bash
+# 2.2.1 — timestamp + slug 결정 (한국어 보존)
+TS=$(node -e "console.log(new Date().toISOString().replace(/[:.]/g,'-'))")
+SLUG=$(node -e "
+const s = process.argv[1].toLowerCase().trim()
+  .replace(/[^a-z0-9가-힣\s-]+/g,'')
+  .replace(/\s+/g,'-')
+  .replace(/-+/g,'-')
+  .replace(/^-|-$/g,'');
+console.log(s.slice(0,40) || 'untitled');
+" "<EXTRACTED_TASK>")
+RUN_ID="run-${TS}-${SLUG}"
+RUN_DIR=".omd/runs/${RUN_ID}"
+
+# 2.2.2 — 표준 서브폴더 생성
+mkdir -p "${RUN_DIR}"/{wireframes,components,assets/briefs,assets/fallback,assets/pinterest-refs,eval/screenshots,persona-feedback,handoff,checkpoints}
+
+# 2.2.3 — task.md
+cat > "${RUN_DIR}/task.md" <<EOF
+# Harness Task
+
+<EXTRACTED_TASK>
+
+---
+
+- run_id: \`${RUN_ID}\`
+- started_at: $(date -u +%Y-%m-%dT%H:%M:%SZ)
+- cwd: \`$(pwd)\`
+EOF
+
+# 2.2.4 — run.log
+echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] run initialized" > "${RUN_DIR}/run.log"
+
+# 2.2.5 — .omd/.gitignore (idempotent)
+mkdir -p .omd
+[ -f .omd/.gitignore ] || printf "runs/\ncache/\n" > .omd/.gitignore
+
+# 2.2.6 — INDEX.md (idempotent header + append)
+INDEX=".omd/runs/INDEX.md"
+[ -f "${INDEX}" ] || cat > "${INDEX}" <<EOF
+# Harness Runs Index
+
+One line per run. Append-only.
+
+EOF
+TASK_ONELINE=$(echo "<EXTRACTED_TASK>" | tr '\n' ' ' | cut -c1-120)
+echo "- $(date -u +%Y-%m-%dT%H:%M:%SZ) \`${RUN_ID}\` — ${TASK_ONELINE}" >> "${INDEX}"
+
+# 2.2.7 — 결과 출력 (이 스킬이 파싱)
+echo "RUN_DIR=${RUN_DIR}"
+echo "RUN_ID=${RUN_ID}"
+```
+
+### 2.3 Hard verify gate (master spawn 차단 조건)
+
+부트스트랩 다음, master spawn 전에 반드시:
+
+```bash
+test -d "${RUN_DIR}" && test -f "${RUN_DIR}/task.md" && echo "OK" || echo "FAIL"
+```
+
+`OK`가 출력되지 않으면 master는 절대 spawn하지 않는다. 사용자에게:
+
+```
+하네스 부트스트랩이 실패했어요 (run dir or task.md 누락). 디스크 권한·경로 문제일 수 있어요. 다시 시도하거나 .omd/ 디렉토리를 정리해주세요.
+```
+
+이 gate를 통과해야만 Step 3로.
+
+## Step 3 — DESIGN.md 존재 확인 + reference 의미 매칭
+
+프로젝트 루트에 DESIGN.md 없으면 reference를 직접 추천한다. 외부 API 호출 없음.
+
+### 3.1 카탈로그 로드
+
+다음 파일을 Read 툴로 전체 로드:
+
+- `.claude/data/reference-fingerprints.json` — 67개 reference의 fingerprint (tone keywords, visual theme, antipatterns, signature motion, has_personas, category)
+- `.claude/data/reference-tags.md` — 사람-읽기용 keyword 매트릭스
+- `.claude/data/vocabulary.json` — controlled vocab
+
+`.claude/data/`에 없으면 `node_modules/oh-my-design-cli/data/` 또는 패키지 root `data/` 에서 fallback.
+
+### 3.2 사용자 task 분석 (silent)
+
+- controlled-vocab 키워드 추출 (예: "헬스/웰니스 / calm-blue / 차분" → `[calm, minimal, approachable, warm]`)
+- 명시 brand hint (예: "토스 같은" → `["toss"]`)
+- 카테고리 추측 (Consumer / Productivity / Fintech / AI / Developer Tools / Design Tools / Automotive / Aerospace / SaaS / Enterprise)
+
+### 3.3 점수 계산 (in-head, 결정론적)
+
+- 각 ref의 `tone_keywords` ∩ task keywords → 1점/매칭
+- brand hint match → +5점
+- 카테고리 일치 → +1점
+- top 5 정렬
+
+### 3.4 검증 (hallucination 방지)
+
+추천하는 모든 id는 `reference-fingerprints.json`의 `items[].id`에 **반드시** 존재해야 한다. 없는 id는 만들어내지 않는다.
+
+### 3.5 사용자에게 제시 (자연어 prose)
+
+라벨 없이, 추천을 statement로:
+
+```
+DESIGN.md가 없어서 reference 한 개를 골라 부트스트랩할게요. <task 핵심 한 줄>을 보니 <top1.id>가 가장 잘 맞을 것 같아요 — <visual_theme 핵심 + 매칭 키워드 1-2개를 한 줄로>.
+
+이대로 가시려면 go (또는 <top1.id>).
+다른 후보: <top2.id> (한 줄 이유) · <top3.id> (...) · <top4.id> (...) · <top5.id> (...)
+본인이 아는 다른 reference면 한 줄로 id만 (예: vercel) — 67개 카탈로그에 없으면 알려드립니다.
+```
+
+### 3.6 사용자 응답 처리
+
+- `go` 또는 reference id (top-5 안) → 그 id로 master spawn
+- 다른 reference id (top-5 밖이지만 카탈로그 안) → 동일하게 진행
+- 카탈로그에 없는 id → "해당 id는 67개 카탈로그에 없어요. top-5 중에서 골라주세요."
+- `중단` → 종료
+
+## Step 4 — Master 호출 (handoff loop)
+
+Subagent (master)는 AskUserQuestion 직접 호출 불가 (main-thread 전용). file-based handoff 패턴으로 돌린다.
+
+### 루프 의사코드
+
+```
+spawn_count = 0
+prompt = "<RUN_DIR + task + chosen_ref_id>. Phase 1부터 시작."
+
+while spawn_count < 12 (safety cap):
+  result = Agent({
+    subagent_type: "omd-master",
+    description: "Run design harness round N",
+    prompt: prompt
+  })
+  spawn_count += 1
+
+  handoff_path = "<RUN_DIR>/.handoff.json"
+  if not exists(handoff_path):
+    relay result text to user; halt
+
+  handoff = JSON.parse(Read(handoff_path))
+
+  if handoff.user_prose:
+    print handoff.user_prose to user
+
+  if handoff.status == "done": halt
+  if handoff.status == "error": halt + show
+  if handoff.status == "ask_user":
+    questions = JSON.parse(Read(handoff.questions_file))
+    answers = AskUserQuestion({ questions: questions.questions })
+    answers_file = "<RUN_DIR>/checkpoints/<handoff.checkpoint_id>.answers.json"
+    Write(answers_file, JSON.stringify({checkpoint_id, answers}))
+    prompt = "continue checkpoint:" + handoff.checkpoint_id + " — answers at " + answers_file
+```
+
+### Safety cap
+
+한 번의 `/omd-harness` 호출에 최대 12 spawn. 초과 시 사용자에게 escalate ("master가 12 spawn 초과, 멈춥니다 — run dir 보존").
+
+### 재진입
+
+사용자가 자연어로 "go" / "fix X" 답하면 동일 loop 재시작. master는 `.handoff.json` 보고 어디까지 갔는지 파악.
+
+## 사용자 체크포인트 처리
+
+Master가 체크포인트에서 turn을 종료한 후 다음 사용자 메시지가:
+
+- **하네스 컨텍스트 안의 응답** (예: "go", "fix the home screen IA", "stop") → master 재spawn + 그대로 전달
+- **다른 작업으로 바뀐 메시지** → run 디렉토리에 `paused.flag` 생성. 나중에 `/omd-harness resume` 하면 재개
+
+## 산출물 위치 (master가 emit, 이 스킬은 안내만)
+
+```
+.omd/runs/run-<ts>-<slug>/
+├── task.md
+├── brief.md
+├── references-cited.md
+├── journey.mmd
+├── wireframes/
+├── DESIGN.md.patch
+├── components/
+│   ├── manifest.json
+│   └── microcopy.json
+├── assets/
+│   ├── brief.md
+│   ├── manifest.json
+│   ├── briefs/
+│   ├── fallback/
+│   └── pinterest-refs/
+├── eval/
+│   ├── deterministic.json
+│   ├── jury.json
+│   └── screenshots/
+├── persona-feedback/
+│   └── <persona>.json
+├── critique.md
+├── handoff/
+│   ├── v0.zip
+│   ├── cursor.zip
+│   └── subframe.zip
+├── run.log
+└── postmortem.md
+```
+
+## 이 스킬이 하지 않는 것
+
+- Phase 로직 실행 (master)
+- Sub-agent 직접 spawn (master)
+- 사용자 응답 해석/라우팅 (master)
+- DESIGN.md 직접 수정 (Phase 5에서 master)
+
+## 금지
+
+- Master 없이 phase를 직접 수행하지 말 것
+- 사용자 체크포인트를 자동 승인하지 말 것
+- Run 디렉토리를 임의로 정리/삭제하지 말 것
+- Step 2.3 verify gate 통과 전에 master spawn 절대 금지

package/skills/omd-learn/SKILL.md

@@ -5,19 +5,18 @@ description: "누적된 preference 교정사항을 DESIGN.md에 반영합니다.
 
 # omd:learn — Preference Fold into DESIGN.md
 
-`.omd/preferences.md`에 누적된 `status: pending` 교정사항을 DESIGN.md에 반영하고, 반영된 엔트리의 상태를 `applied`로 플립한다.
+`.omd/preferences.md`에 누적된 `status: pending` 교정사항을 DESIGN.md에 반영하고, 반영된 엔트리의 상태를 `applied`로 플립한다. **CLI 호출 없음** — Read/Edit 툴로 직접 처리.
 
 ## Phase 1 — 검토
 
-Bash 툴로:
+`Read .omd/preferences.md` → frontmatter + 엔트리들 파싱:
 
-```bash
-omd learn
-```
+- 엔트리 분리: `## ` heading 기준 split
+- 각 엔트리의 `omd-meta` 코드블록에서 `id`, `scope`, `status` 추출
+- `status: pending`만 필터
 
-실행하면 pending 엔트리를 scope별로 그룹화해서 보여준다. 출력을 읽고 사용자에게 **그룹별 요약**을 제시한다 (각 엔트리를 나열하지 말고, scope당 2-3줄로 의도 정리).
+scope별로 그룹화해서 사용자에게 요약:
 
-예시 출력 형식:
 ```
 components.button (3 pending):
   - CTAs never uppercase (pref_xxx, pref_yyy)
@@ -27,55 +26,76 @@ spacing (1 pending):
   - 8pt grid, not 4pt (pref_aaa)
 ```
 
+엔트리당 한 줄이 아니라 **scope당 2-3줄로 의도 정리**.
+
 ## Phase 2 — 사용자 확인
 
-"이 교정들을 DESIGN.md에 반영할까요?" 묻는다. 사용자가 동의하면 Phase 3.
+"이 교정들을 DESIGN.md에 반영할까요?" 묻기. 동의 → Phase 3.
+
+거부 → 어떤 scope를 reject할지 묻고 Phase 4 reject 분기로.
 
-## Phase 3 — 적용
+## Phase 3 — DESIGN.md 적용
 
-1. **DESIGN.md를 Read 툴로 로드**한다.
-2. scope별로 묶어서 **하나의 coherent edit**을 생성한다 (엔트리당 하나의 edit이 아니라, 한 scope의 교정들을 종합).
-3. Edit 툴로 DESIGN.md의 해당 섹션을 수정.
-4. **voice 섹션이나 내러티브를 수정할 때는 DESIGN.md의 기존 문체를 preserve**한다 — 교정 내용만 반영하되 문장 스타일, 길이, 톤은 유지.
-5. 수정 후 `DESIGN.md`의 새 hash를 계산. Bash:
-   ```bash
-   omd sync --force  # shim들의 hash 갱신 (DESIGN.md 해시는 pointer라 바뀌지 않지만 lock만 업데이트)
-   ```
+1. `Read DESIGN.md` 로드
+2. scope별로 묶어서 **하나의 coherent edit** 생성 (엔트리당 하나가 아니라 한 scope의 교정들을 종합)
+3. Edit 툴로 DESIGN.md의 해당 섹션 수정:
+   - `components.button` → DESIGN.md §8 (Components → Button) 또는 §13 (Components 상세)
+   - `color` → §2 (Color Palette)
+   - `typography` → §3
+   - `spacing` → §4 (Spacing scale)
+   - `voice` → §10 (Voice & Tone)
+   - `motion` → §15 (Motion & Easing)
+   - `visualTheme` → §1 (Visual Theme)
+4. **voice/내러티브 수정 시 DESIGN.md의 기존 문체 preserve** — 교정 내용만 반영, 문장 스타일/길이/톤 유지
+5. **§10-15 (Brand Philosophy 레이어)는 reference voice 보존이 우선** — preference가 §10-15 본문 자체를 다시 쓰라고 하지 않는 한 본문은 건드리지 않고 §1-9의 axes만 수정
 
 ## Phase 4 — 상태 플립
 
-반영한 각 엔트리에 대해:
+반영한 엔트리: 해당 엔트리의 omd-meta 블록을 Edit 툴로:
+- `status: pending` → `status: applied`
+- `applied_at: <ISO timestamp>` 라인 추가
+- (선택) `applied_design_md_hash: <DESIGN.md sha256>` 추가. hash 계산:
+  ```bash
+  node -e "console.log(require('crypto').createHash('sha256').update(require('fs').readFileSync('DESIGN.md')).digest('hex').slice(0,12))"
+  ```
 
-```bash
-omd learn --mark-applied <pref_id>
-```
+거부한 엔트리:
+- `status: pending` → `status: rejected`
+- `rejected_reason: "<짧은 이유>"` 라인 추가
 
-반영 안 한 엔트리(충돌, 거부)는:
-
-```bash
-omd learn --mark-rejected <pref_id> --reason "<짧은 이유>"
-```
+상위 엔트리가 누적된 작은 교정을 통합·대체했으면:
+- 작은 엔트리들은 `status: superseded`
+- `superseded_by: <상위 pref_id>` 추가
 
 ## Phase 5 — 결과 요약
 
-한 문단으로:
+한 문단:
 - 반영된 교정 수 (scope별)
 - 거부된 교정 수 + 이유
-- 사용자에게 `.omd/preferences.md` 직접 확인 링크 안내
+- 사용자에게 `.omd/preferences.md` 직접 확인 안내
 
-예시:
 ```
-✓ 4 preferences applied to DESIGN.md
+4 preferences applied to DESIGN.md
   - components.button: CTAs never uppercase, primary brand-500
   - spacing: 8pt grid
-✗ 1 rejected (conflicts with base reference radius)
+1 rejected (conflicts with base reference radius)
 
 Review .omd/preferences.md for details.
 ```
 
+## 옵션 패턴
+
+사용자가 특정 작업만 요청하는 경우:
+
+- **"pending만 보여줘"** → Phase 1만, Phase 2-5 생략
+- **"X scope만 반영"** → 해당 scope만 Phase 3에서 처리
+- **"<pref_id>를 applied로 표시"** → Phase 4의 single-entry 플립만
+- **"<pref_id>를 rejected로 표시 + 이유"** → 동일
+
 ## 금지
 
-- LLM으로 엔트리별 개별 diff를 생성하지 말 것 — scope별 합쳐서 하나의 coherent edit.
-- DESIGN.md의 section 구조(heading 계층)를 바꾸지 말 것.
-- 교정과 관계없는 부분을 "개선"하지 말 것.
-- pending을 건너뛰지 말 것 — 모든 pending에 대해 applied or rejected 플립해야 한다.
+- LLM으로 엔트리별 개별 diff를 생성하지 말 것 — scope별 합쳐서 하나의 coherent edit
+- DESIGN.md의 section heading 계층을 바꾸지 말 것
+- 교정과 관계없는 부분을 "개선"하지 말 것
+- pending을 건너뛰지 말 것 — 모든 pending에 applied/rejected/superseded 중 하나로 플립
+- omd-meta 블록 외부 (body) 수정 금지 — 교정 본문은 영구 기록

package/skills/omd-remember/SKILL.md

@@ -5,7 +5,7 @@ description: "디자인 선호/교정을 .omd/preferences.md 에 append합니다
 
 # omd:remember — Preference Logger
 
-사용자의 디자인 선호/교정을 `.omd/preferences.md`에 append-only로 기록한다. 나중에 `omd:learn`이 배치로 DESIGN.md에 반영.
+사용자의 디자인 선호/교정을 `.omd/preferences.md`에 append-only로 기록한다. 나중에 `omd:learn`이 배치로 DESIGN.md에 반영. **CLI 호출 없음** — Read/Edit/Write 툴로 직접 처리.
 
 ## 트리거 발화 패턴
 
@@ -15,30 +15,108 @@ description: "디자인 선호/교정을 .omd/preferences.md 에 append합니다
 - "rule of thumb: ..."
 - 사용자가 당신의 디자인 선택을 명시적으로 교정
 
-## 실행
+## 파일 포맷 (`.omd/preferences.md`)
 
-Bash 툴로 한 번 실행:
+frontmatter + 엔트리 시퀀스. 엔트리 하나당 `## <heading>` + `omd-meta` 코드블록 + body.
 
+```
+---
+schema: omd.preferences/v1
+design_md_hash_at_creation: <hash 또는 빈 문자열>
+---
+
+# Preference Log
+
+## 2026-04-30T17:48:00.000Z — ctas-never-uppercase
+
+​```omd-meta
+id: pref_lqxk2_a3f9c1d4
+timestamp: 2026-04-30T17:48:00.000Z
+scope: components.button
+signal: user-statement
+confidence: explicit
+status: pending
+source_agent: claude-code
+source_context: "src/components/Button.tsx"
+​```
+
+CTAs are never uppercase
+```
+
+## 실행 절차
+
+### Step 1 — note 정규화
+사용자 발화를 한 문장 영문으로 요약 (예: "앞으로 CTA 대문자 쓰지마" → `CTAs are never uppercase`).
+
+### Step 2 — scope 추론
+note 내용에서 다음 매핑 우선순위 사용:
+
+| 매칭 키워드 (정규식, case-i) | scope |
+|---|---|
+| `\b(buttons?\|ctas?\|btns?)\b` | `components.button` |
+| `\b(cards?)\b` | `components.card` |
+| `\b(dialogs?\|modals?)\b` | `components.dialog` |
+| `\b(inputs?\|fields?\|forms?)\b` | `components.input` |
+| `\b(nav\|navigation\|headers?\|menus?)\b` | `components.navigation` |
+| `\b(badges?\|chips?\|pills?\|tags?)\b` | `components.badge` |
+| `\b(tables?\|rows?\|cells?)\b` | `components.table` |
+| `\b(dropdowns?\|selects?\|comboboxes?)\b` | `components.dropdown` |
+| `\b(toasts?\|notifications?\|snackbars?)\b` | `components.toast` |
+| `\b(tabs?)\b` | `components.tabs` |
+| `\b(colors?\|palette\|hex\|hue\|saturation\|shades?\|tints?\|gradients?)\b` | `color` |
+| `\b(font\|typography\|typeface\|weight\|leading\|tracking\|letter-?spacing)\b` | `typography` |
+| `\b(spacing\|gap\|padding\|margin\|grid)\b` | `spacing` |
+| `\b(voice\|tone\|copy\|microcopy\|wording\|language)\b` | `voice` |
+| `\b(motion\|animation\|transition\|easing\|duration)\b` | `motion` |
+| `\b(layout\|structure\|hierarchy)\b` | `layout` |
+| `\b(theme\|aesthetic\|vibe\|mood\|look\|feel)\b` | `visualTheme` |
+| (어느 것도 매칭 X) | `visualTheme` |
+
+사용자가 명시적으로 scope를 지정했으면 그대로 사용.
+
+### Step 3 — id 생성
+형식: `pref_<base36 timestamp>_<8 hex chars>`. Bash로 한 줄:
 ```bash
-omd remember "<사용자 발화를 한 문장 영문으로 요약>"
+node -e "console.log('pref_' + Date.now().toString(36) + '_' + require('crypto').randomBytes(4).toString('hex'))"
 ```
 
-옵션:
-- `--scope <value>` — 명시적으로 지정할 때. 기본값은 note 내용에서 자동 추론. 허용: `visualTheme | color | typography | spacing | voice | motion | layout | components.<name>`
-- `--context <text>` — 관련 파일 경로나 PR 번호 (e.g. `src/components/Button.tsx`, `#1234`)
-- `--agent <name>` — 보통 생략 (환경변수 자동 감지). override 필요 시: `claude-code | codex | opencode | cursor`
+### Step 4 — slug + heading
+```bash
+node -e "console.log(process.argv[1].toLowerCase().replace(/[^a-z0-9]+/g,'-').replace(/^-+|-+$/g,'').slice(0,40) || 'entry')" "<note>"
+```
+heading: `<ISO timestamp> — <slug>`
+
+### Step 5 — 파일 read/append
+1. `Read .omd/preferences.md` — 없으면 frontmatter+header부터 만든다:
+   ```
+   ---
+   schema: omd.preferences/v1
+   design_md_hash_at_creation:
+   ---
+
+   # Preference Log
 
-## 응답
+   ```
+2. 새 엔트리 블록을 **파일 끝에 append** (Edit 툴, old_string은 마지막 라인, new_string은 마지막 라인 + 빈 줄 + 새 엔트리). 또는 Write로 전체 재작성.
+3. 메타 필드:
+   - `id`, `timestamp`, `scope` (필수)
+   - `signal: user-statement` (디폴트, 사용자가 직접 발화한 경우) 또는 `user-correction` (사용자가 당신의 선택을 교정한 경우)
+   - `confidence: explicit` (디폴트, 사용자가 명시적으로 말한 경우) 또는 `inferred` (당신이 사용자 행동에서 추론한 경우)
+   - `status: pending` (모든 새 엔트리)
+   - `source_agent`: 환경에서 추론 (`claude-code` / `codex` / `opencode` / `cursor`)
+   - `source_context`: 관련 파일 경로 또는 PR번호 (있으면 JSON.stringify로 quote)
 
-커맨드 출력(`Logged pref_xxx ... → ./.omd/preferences.md`)을 그대로 보여주면 된다. 사용자에게 장황한 확인 불필요.
+### Step 6 — 응답
+간결한 한 줄: `Logged ${id} to .omd/preferences.md (scope: ${scope})`
 
 ## omd:apply 스킬과의 관계
 
-- **자동 감지**: 일반 UI 작업 중 교정이 발생하면 `omd:apply` 스킬이 자동으로 이 커맨드를 호출한다.
-- **명시적 호출**: 사용자가 UI 작업 없이 디자인 원칙을 선언하는 경우, 이 스킬이 직접 트리거된다.
+- **자동 감지**: 일반 UI 작업 중 교정 발생 시 `omd:apply`가 이 스킬 트리거
+- **명시적 호출**: 디자인 원칙 선언만 할 때 직접 트리거
 
 ## 금지
 
-- `.omd/preferences.md` 파일을 직접 편집하지 말 것 — 항상 `omd remember` 경유.
-- 같은 내용을 중복 기록하지 말 것 (같은 세션 내에서).
-- 사용자에게 "기록할까요?" 묻지 말 것 — 감지 즉시 기록 + 간결 알림.
+- `.omd/preferences.md` 파일을 frontmatter 외 직접 손대지 말 것 (id 충돌 방지) — 항상 위 절차로
+- 같은 세션 내 동일 내용 중복 기록 금지
+- 사용자에게 "기록할까요?" 묻지 말 것 — 감지 즉시 기록 + 간결 알림
+- frontmatter의 `design_md_hash_at_creation`은 첫 생성 시에만 채움 (이후 절대 수정 X)