oh-my-oop 0.2.0

package/MCP_STRUCTURE.md

@@ -0,0 +1,301 @@
+# MCP 소스 구조 가이드 (oh-my-oop)
+
+`src/oop/commands.ts`가 MCP/CLI 공통 코어입니다. `src/cli.ts`는 JSON CLI, `src/application/discovery.ts`는 OOP 명령 스키마 발견을 담당합니다. 아키텍처/실행기/JEV 모듈은 분리했습니다. 현재 제품 경계는 `SCOPE.md`를 읽으세요.
+
+> **목적:** 다음 세션이 빠르게 MCP 룰/도구 확장 작업에 들어갈 수 있도록.
+> **마지막 정찰:** 2026-05-23 (lotto 141 PR 분석 직후, 룰 확장 작업 진입 전)
+
+---
+
+## 1. 디렉토리 구조
+
+```
+src/
+├── index.ts                 ← entry point (stdio transport)
+├── server.ts                ← McpServer 생성 + 도구/리소스/프롬프트 등록
+├── config.ts                ← .oop/ 워크스페이스 위치 해석
+│
+├── domain/                  ← 도메인 모델 (CRC 카드, 유스케이스, 협력)
+│   ├── ids.ts
+│   ├── model.ts             ← CrcCard, UseCase, Collaboration, Design 타입
+│   ├── schemas.ts           ← Zod 스키마 (TradeoffQuestion 등)
+│   └── stereotypes.ts       ← Wirfs-Brock 5종 + fits/misfits 힌트
+│
+├── io/                      ← 파일 시스템 영속화 (.oop/ markdown frontmatter)
+│   ├── classStore.ts        ← CrcCard CRUD
+│   ├── useCaseStore.ts
+│   ├── collaborationStore.ts
+│   ├── designIndex.ts       ← .oop/index.json 관리
+│   ├── design.ts            ← loadDesign() — 모든 카드/유스케이스/협력 통합 로딩
+│   ├── frontmatter.ts       ← gray-matter wrapper, nowIso()
+│   ├── history.ts           ← Before/After 비교용 스냅샷
+│   └── workspace.ts         ← .oop/ 부트스트랩 (oop_init)
+│
+├── tools/                   ← MCP 도구 등록 (각 파일 = 1~2개 도구)
+│   ├── index.ts             ← registerAllTools() 진입점
+│   ├── init.ts              ← oop_init
+│   ├── useCases.ts          ← oop_use_case_add, oop_use_case_list
+│   ├── responsibilities.ts  ← oop_propose_responsibilities, oop_assign_responsibility
+│   ├── classes.ts           ← oop_class_upsert, oop_class_list
+│   ├── collaborations.ts    ← oop_collaboration_define
+│   ├── alternatives.ts      ← oop_propose_alternatives
+│   ├── diagram.ts           ← oop_diagram_generate (Mermaid)
+│   ├── compare.ts           ← oop_design_compare (Before/After)
+│   ├── validate.ts          ← oop_design_validate
+│   └── state.ts             ← oop_state_read
+│
+├── validate/                ← 검증 룰 (각 파일 = 1개 룰)
+│   ├── rules.ts             ← ALL_RULE_IDS, validateDesign() dispatch
+│   ├── findings.ts          ← Finding/Remedy/Severity 타입 + assertHasMultipleRemedies
+│   ├── godObject.ts         ← 책임/협력자 임계치 초과
+│   ├── cohesion.ts          ← low-cohesion
+│   ├── coupling.ts          ← too-many-collaborators
+│   ├── testability.ts       ← non-newable, side-effect-in-holder, mocking-pressure
+│   ├── cycle.ts             ← 순환 의존
+│   ├── vagueName.ts         ← Validator/Manager/Helper 등 god-name (racingcar 인용)
+│   ├── validationLocation.ts ← 검증 분산 (UI 형식 vs 입력 정책 vs 도메인 invariant 3분류)
+│   ├── dependencyDirection.ts ← Domain → UI 역방향 의존 (BeokBeok 인용)
+│   ├── dataDuplication.ts   ← knowing 책임 중복
+│   └── functionNotObject.ts ← 함수형 클래스 (= 정적 유틸)
+│
+├── tradeoff/                ← N개 대안 + 트레이드오프 생성
+│   ├── engine.ts            ← generateAlternatives() + attachReflectionQuestions()
+│   ├── templates.ts         ← expansion_prompt 텍스트
+│   └── heuristics/
+│       ├── classSplit.ts
+│       ├── collaborationShape.ts
+│       ├── responsibilitySplit.ts ← by-noun/by-verb/by-stereotype/single-class
+│       └── stereotypeChoice.ts
+│
+├── prompts/                 ← MCP 프롬프트 (대화 시드)
+│   ├── index.ts
+│   ├── rddIntro.ts          ← /rdd-workshop-intro
+│   ├── discovery.ts
+│   └── review.ts            ← /design-review-cho-younghos-lens
+│
+├── render/
+│   ├── mermaid.ts           ← Mermaid classDiagram 생성
+│   ├── diff.ts
+│   └── sideBySide.ts
+│
+├── resources/
+│   └── index.ts
+│
+└── util/
+    ├── log.ts
+    └── mcp.ts               ← jsonResult, errorResult 헬퍼
+
+test/
+├── unit/
+├── integration/
+├── kotlin-racingcar/        ← racingcar 미션 케이스
+└── fixtures/
+
+lessons/                     ← PR 분석 데이터셋 (정적 자산)
+├── STYLE_GUIDE.md
+├── woowacourse-kotlin-lotto/    ← 141 PR 분석 (2026-05-22 완료)
+└── woowacourse-racingcar/       ← 이전 분석
+```
+
+---
+
+## 2. 핵심 계약 (반드시 지킬 것)
+
+### 2-1. `Finding`은 항상 ≥2개 `remedies`
+```ts
+// validate/findings.ts
+assertHasMultipleRemedies(finding)  // throw if < 2 remedies
+```
+→ 모든 새 룰은 *최소 2개 대안 remedy + pros/cons*를 자동 첨부해야 함. 단일 권고 금지 (조영호 철학).
+
+### 2-2. 모든 도구는 jsonResult/errorResult 사용
+```ts
+// util/mcp.ts
+return jsonResult({ ... });
+return errorResult((e as Error).message);
+```
+
+### 2-3. 도구 description은 *[USE WHEN] ... + 호출 시점* 명시
+- validate.ts 참고: "'리뷰'/'검토'/'평가'해달라거나, 'god object 같지 않아?'를 물을 때"
+
+### 2-4. `AlternativeSeed`는 항상 `reflection_questions` 첨부
+- `tradeoff/engine.ts::attachReflectionQuestions()` 가 자동 부착
+- `testability_justification` + `expansion_pressure` 2개 강제
+
+### 2-5. 도메인 종속 룰/도구 금지 (general-OOP 원칙)
+
+`src/` 의 모든 룰, tradeoff heuristic, 도구, prompt, stereotype 은 **어떤 도메인에도 적용 가능**한 일반 OOP 패턴이어야 한다. 도메인 종속 어휘(블랙잭의 Ace, 로또의 Bonus, 자동차 경주의 Move 등)는 *룰 시그니처/이름/판정 로직*에 등장하지 않는다.
+
+**허용**: `lessons/<mission>/` 의 PR 인용을 evidence/remedy 에 첨부. `vagueName.ts` 가 racingcar `@vagabond95` 인용한 패턴과 동일. 도메인 어휘는 *근거*로만 등장한다.
+
+**금지 예시**:
+- `ace-bonus-while-anti-pattern` 룰 (블랙잭 Ace 한정)
+- `blackjack-rule-fidelity` 룰 (블랙잭 룰 명세)
+- `lotto-bonus-number-locus` 룰 (로또 한정)
+- `/blackjack-phase2-entry` prompt (블랙잭 단계명)
+
+**허용 예시**:
+- `value-arithmetic-invariant-conflict` 룰 (값 객체 산술 일반)
+- `dual-purpose-knowing` 룰 (한 데이터 두 책임 일반)
+- `/phase-pressure-test` prompt (단계 진화 일반)
+- 위 룰의 evidence 에 *"블랙잭 BettingMoney → Profit 분리"* PR 인용
+
+**판단 기준**: *룰 이름·시그니처·판정 로직에서 그 도메인 어휘를 제거해도 일반 OOP 안티패턴인가?* 그렇다면 일반. 아니면 도메인 종속이므로 거부.
+
+**Stereotype 5종 동결**: 현재 5종 (Knowing/Doing/Controller/Coordinator/Structurer) + Interfacer 는 *추상화 정점*이다. 도메인 stereotype (Participant/Dealer/Judge 등) 은 추가하지 않고, 도메인 역할은 카드 `metadata.role`(자유 텍스트)로 표현한다. fits/misfits 일관성 유지 비용과 학생 분류 부담이 폭증하기 때문.
+
+**룰 폭증 회피 동반 원칙**: 신규 룰 1개 추가 = *기존 룰 인용 보강 ≥2개* 동반. lessons 코퍼스의 발견은 *기존 룰 강화로 흡수 가능한지* 먼저 검토하고, 흡수 불가일 때만 신규 룰.
+
+---
+
+## 3. 신규 룰 추가 방법 (체크리스트)
+
+1. `src/validate/<ruleName>.ts` 생성 (godObject.ts 패턴 그대로)
+2. `check<RuleName>(design: Design, ...): Finding[]` 함수 export
+3. `validate/rules.ts`:
+   - import 추가
+   - `ALL_RULE_IDS` 배열에 ID 추가
+   - `validateDesign()`의 if 체인에 호출 추가
+   - 임계치 필요하면 `DEFAULT_THRESHOLDS`에 추가
+4. 모든 finding에 `assertHasMultipleRemedies()` 감싸기 (≥2 remedies 강제)
+5. `test/unit/validate.rules.test.ts`에 테스트 케이스 *추가* (모듈당 1 파일, 평면 구조 — 디렉토리 분리 X). 케이스 패턴: positive 1개 + suppression(skip) negative 2~3개. 마지막 `all rules pass the >=2 remedies contract` 케이스가 신규 룰도 자동 검증.
+
+---
+
+## 4. 기존 18개 룰 ↔ 코퍼스 안티패턴 매핑
+
+이미 lotto/racingcar/blackjack 에서 본 안티패턴 중 **이미 룰로 존재하는 것**:
+
+| 안티패턴 | 룰 ID | 비고 |
+|---|---|---|
+| Validator/Verifier/Picker/Distributor/Judge god-name | `vague-class-name` | racingcar 추출. blackjack 으로 가상 객체 사전 +14 + laco-dev/ghojeong 인용 보강 |
+| Controller god-object / Dealer 이중 역할 | `god-object` | 책임/협력자 임계치 + blackjack ghojeong "사람 한 명 더 필요한가" 인용 |
+| 검증 분산 (View + Domain) | `validation-misplacement` | UI 형식/입력 정책/도메인 invariant 3분류 |
+| Domain → View 의존 / enum UI value 침투 | `dependency-direction` | BeokBeok + blackjack laco-dev "Rank 출력 = UI 관심사" 인용 |
+| toString 도메인 침투 | `dependency-direction` 부분 + `mixed-stereotype` | UI 어휘 + InformationHolder misfits 힌트 |
+| Tell-Don't-Ask 위반 / 외부 비교자 (Judge.judge) | `feature-envy` | knowing 점수 기반 + blackjack laco-dev/BeokBeok 메시지 어휘 인용 |
+| 양방향/순환 의존 | `cycle` | |
+| 단일 위임만 하는 객체 | `function-not-object` 일부 | 좀 다름. 추가 룰 필요할 수 있음 |
+| 모호한 책임 혼합 | `mixed-stereotype` | knowing+doing+coordinating 모두 |
+| 미사용 클래스 | `orphan-class` | |
+| 데이터 중복 | `data-source-duplication` | knowing 토큰 중복 |
+| 빈 InformationHolder + 외부 mutation | `empty-object-external-fill` | lotto malibinYun 인용 |
+| 행위 없는 컬렉션 wrapper | `collection-wrapper-without-behavior` | lotto krrong 인용 |
+| 값 wrapper invariant 부재 / BettingMoney 산술 invariant 충돌 | `primitive-wrapper-without-invariant` | lotto junjange + blackjack malibinYun "BettingMoney → Profit" 인용 |
+| 전략 그룹 knowing 비대칭 | `strategy-default-param-pollution` | lotto krrong 인용 |
+| doing 과도 분해 | `function-decomposition-excess` | lotto 일반 가르침 |
+| 한 데이터 두 책임 (출력 vs 비교) | `dual-purpose-knowing` | blackjack laco-dev "strength vs displayScore" — Phase 1 신규 |
+| 도메인 상태 보유 전역 객체 (Singleton Deck) | `singleton-stateful-holder` | blackjack malibinYun "53번 뽑으면 오류?" — Phase 1 신규 |
+
+---
+
+## 5. 추가 룰 후보 (lotto에서 새로 발견)
+
+### ✅ 추가 완료 — lotto 코퍼스 (2026-05-23, 세션 2)
+1. **`empty-object-external-fill`** — InformationHolder + knowing 0 + doing이 모두 mutation 동사 (PR #14 @malibinYun)
+2. **`collection-wrapper-without-behavior`** — Structurer + 단일 컬렉션 knowing + pass-through doing (PR #144 @krrong)
+3. **`primitive-wrapper-without-invariant`** — 값 wrapper 명명 + 단일 원시 knowing + invariant 의도 없음 (PR #58 @junjange, #77 @hxeyexn)
+4. **`strategy-default-param-pollution`** — 같은 전략 suffix 그룹의 knowing 비대칭 (PR #144 @krrong)
+5. **`function-decomposition-excess`** — doing ≥4개 모두 짧은 동사 + 도메인 명사 부재 (lotto 일반 가르침)
+
+### ✅ 추가 완료 — blackjack 코퍼스 (2026-05-28, 세션 3 Phase 1)
+6. **`dual-purpose-knowing`** — InformationHolder/Structurer + 표현(display/format/render/출력) 동사 ≥1 + 비교/판정(compare/judge/strength/비교) 동사 ≥1 동시 등장 (blackjack aprilgom/105 @laco-dev "strength vs displayScore")
+7. **`singleton-stateful-holder`** — InformationHolder/Structurer + notes/name 에 singleton/global 표식 + 가변 컬렉션 knowing (blackjack krrong/46 @malibinYun "53번 뽑으면 오류?")
+
+→ 총 18개 룰 (기존 16 + blackjack 신규 2) = **18개**.
+
+### ✅ 기존 룰 인용 보강 — blackjack 코퍼스 (Phase 2)
+- `vague-class-name` — SUSPECT 사전 +14 (Picker/Distributor/Judge/Rule/Calculator/Information/Info/Decider 등) + laco-dev/ghojeong 가상 객체 회피 인용
+- `dependency-direction` — laco-dev "Rank 출력 = UI 관심사" + galcyurio "domain → ui 반대 문제" 인용
+- `feature-envy` — laco-dev "메시지를 보낸다" + BeokBeok "내 카드 줄테니 알려줘" 인용
+- `god-object` — ghojeong "사람 한 명 더 필요한가" 인용
+- `primitive-wrapper-without-invariant` — malibinYun "BettingMoney 산술이 invariant 깰 때 결과 타입 분리" 인용
+
+### Priority 3 (코드 분석 필요해 룰화 어려움 — 보류)
+- `enum-ordinal-dependency` — Design 모델만으로는 감지 어려움 (코드 AST 필요)
+- `null-assertion-misuse` — 동일
+- `runCatching-on-non-input` — 동일
+
+---
+
+## 6. 추가 트레이드오프 케이스 (`tradeoff/heuristics/`)
+
+### ✅ 추가 완료 (2026-05-23, 세션 2 + 2026-05-28, 세션 3) — `TradeoffQuestion` 10종
+| 케이스 | 위치 | question type | 추가 시점 |
+|---|---|---|---|
+| `data class vs value class` | `heuristics/valueObjectShape.ts` | `value_object_shape` | 세션 2 |
+| `Strategy interface vs enum policy` | `heuristics/strategyOrPolicy.ts` | `strategy_or_policy` | 세션 2 |
+| `runCatching vs null+while` | `heuristics/errorHandling.ts` | `error_handling` | 세션 2 |
+| `일급 컬렉션 채택 여부` | `heuristics/collectionShape.ts` | `collection_shape` | 세션 2 |
+| `두 동등 주체 간 비교 책임 위치` | `heuristics/dualSubjectComparison.ts` | `dual_subject_comparison` | **세션 3 (blackjack)** |
+
+각 4개 대안 + 도메인 어휘 pros/cons + 조영호 렌즈 (cohesion/coupling/testability) 첨부.
+
+기존 5종은 그대로: `responsibility_split`, `class_split`, `collaboration_shape`, `stereotype_choice`, `free_form`.
+
+`검증 위치 (View + Domain 모두 vs 단일)`은 이미 `validationLocation.ts` 룰로 다룸.
+
+### ✅ 학습 장치: 대안 0번 슬롯 (2026-05-28, 세션 3)
+
+`tradeoff/engine.ts::nullOptionFor()` — 모든 `propose_alternatives` 호출에 *"이 객체/분리를 만들지 않는다"* 카드를 0번 슬롯에 자동 prepend. `free_form` 제외 9개 question 별 다른 label.
+
+*답을 받는 게 아니라 문제를 거부하는 카드*를 항상 노출해서 가상 객체 회피를 *학생 자가 자각*하도록 강제. *N안 + 트레이드오프*의 *경험적 체화* 장치.
+
+@laco-dev (blackjack tobae-time/115): *"객체는 모두 스스로 일을 합니다."*
+
+### ✅ prompts 4종 추가 (2026-05-28, 세션 3)
+
+| prompt | 용도 |
+|---|---|
+| `/tell-dont-ask-rephrase` | 외부 비교자/getter → 메시지 호출로 다시 쓰는 4안 + 진단 질문 |
+| `/state-machine-introspect` | sealed State 도입 2 기준 (다형성 + Context 책임) + 4안. 자동 감지 X, 학생 자가 도달 |
+| `/phase-pressure-test` | 추가 요구사항이 깰 부분 학생 자가 진단. 1단계→2단계 학습 장치 |
+| `/imagine-without-controller` | Controller 가상 제거 + 가상 객체 회피 사고 실험 |
+
+기존 3종: `/rdd-workshop-intro`, `/design-discovery`, `/design-review-cho-younghos-lens`. 총 7종.
+
+---
+
+## 7. 빌드/테스트
+
+```bash
+npm run dev          # tsx src/index.ts (dev mode)
+npm run build        # tsc -p . → dist/
+npm test             # vitest run
+npm run test:watch
+```
+
+- TypeScript strict mode, ESM (`"type": "module"`)
+- Node ≥ 18.17
+- 의존성: `@modelcontextprotocol/sdk`, `zod`, `gray-matter`
+
+---
+
+## 8. 다음 세션 진입 시 추천 작업 순서
+
+1. **이 문서 + `validate/godObject.ts` + `validate/vagueName.ts` 읽기** (룰 작성 패턴 익히기)
+2. **`validate/findings.ts` 읽기** (`assertHasMultipleRemedies` 계약 이해)
+3. **Priority 1 룰 1개 선택 (예: `empty-object-external-fill`) 후 PR-ready 수준으로 구현**:
+   - `validate/emptyObjectFill.ts` 작성
+   - `rules.ts`에 등록
+   - `test/unit/validate/emptyObjectFill.test.ts` 작성
+   - `npm test` 통과 확인
+4. **lessons/woowacourse-kotlin-lotto/ 에서 해당 룰이 잡을 PR 예시 1-2개 인용해 evidence/remedy에 첨부** (vagueName.ts 패턴)
+
+---
+
+## 9. lotto PR 분석 자산 활용
+
+`lessons/woowacourse-kotlin-lotto/` — 141 PR 분석 완료 (2026-05-23 사족 정리 끝).
+
+새 룰의 evidence/remedy 작성 시 `lessons/woowacourse-kotlin-lotto/<reviewee>/<PR>.md`에서 *대표 인용* 발췌해 첨부하면 학생에게 *왜*가 즉시 전달됨. (vagueName.ts 가 `@vagabond95` 인용한 패턴과 동일.)
+
+PROGRESS.md에 PR# / reviewee / 코멘트 수 인덱스 있음.
+
+---
+
+## 10. 알려진 한계
+
+- **코드 AST 분석 없음** — 룰은 모두 `.oop/` 설계 모델(CRC/협력) 기반. `enum.ordinal`, `!!`, `runCatching` 같은 코드 패턴은 감지 불가.
+- **lotto의 5종 stereotype 매핑**이 학생 입력 의존 — 자동 추론 안 함.
+- **blackjack 미션 데이터셋 없음** — 향후 분석 가능.

package/README.md

@@ -0,0 +1,167 @@
+# Oh-My-OOP
+
+객체의 책임·역할·협력을 함께 설계하는 OOP/RDD 도구입니다. **Skill + CLI 또는 MCP 중 하나를 선택**하세요. 같은 코어와 같은 `.oop` 설계 데이터를 사용하며, 모델 API 키·JEV·JVM·Docker는 필요하지 않습니다.
+
+## 사용 방식 선택
+
+| | Skill + CLI | MCP |
+|---|---|---|
+| 실행 | 에이전트가 Skill을 읽고 CLI 호출 | 에이전트가 `oop_*` 도구 호출 |
+| 필요한 환경 | Agent Skills 지원, 파일 읽기·명령 실행 권한, Node.js | 로컬 stdio MCP 지원, Node.js |
+| 설치 | 호스트의 Skill 디렉터리에 설치 | 호스트에 MCP 서버 등록 |
+| 상대 방식 필요? | MCP 연결 불필요 | Skill 설치 불필요 |
+
+둘 다 설치할 수도 있지만 같은 변경을 두 번 실행하지 마세요. Skill과 MCP의 프롬프트/리소스 전달 방식은 다르며, 보장하는 공통 부분은 OOP 연산과 저장 형식입니다.
+
+## 공통 준비
+
+배포 코어의 실행 최소 버전은 Node.js 18.17입니다. 신규 설치는 유지보수 중인 Node.js 버전을 권장합니다. npm에서 코어를 설치하면 소스를 직접 빌드할 필요가 없습니다.
+
+```sh
+npm install -g oh-my-oop@0.2.0
+oh-my-oop --version
+```
+
+전역 설치를 원하지 않으면 대상 프로젝트에서 `npm install --save-dev oh-my-oop@0.2.0`으로 설치하고 에이전트에 `node /absolute/my-project/node_modules/oh-my-oop/dist/index.js` 경로를 명시하세요.
+
+소스 수정·개발을 하려면 다음 방법을 사용합니다. 개발 의존성(Vitest/Vite) 때문에 Node.js 22.12 이상인 22.x 또는 24 이상이 필요합니다.
+
+```sh
+git clone https://github.com/no1msh/Oh-My-OOP.git
+cd Oh-My-OOP
+npm ci
+npm run build
+node dist/index.js --help
+```
+
+이미 저장소가 있다면 clone 없이 해당 디렉터리에서 빌드하세요.
+
+## A. Skill로 사용하기
+
+배포·에이전트 선택은 [Vercel Skills CLI](https://github.com/vercel-labs/skills)에 맡깁니다. `npx skills`는 Skill 안내 파일을 설치하고, **실제 검사는 별도로 준비한 `oh-my-oop` CLI가 실행**합니다. MCP 연결은 필요 없습니다.
+
+### 1. 실행 코어 준비
+
+공통 준비에서 npm으로 설치했다면 완료입니다. 소스로 빌드했다면 저장소 디렉터리에서 아래 명령으로 CLI를 PATH에 연결할 수 있습니다.
+
+```sh
+npm link
+oh-my-oop --version
+```
+
+`npm link`는 로컬 소스를 npm의 전역 prefix에 연결합니다. 전역 연결을 원하지 않으면 건너뛰고 에이전트에 `node /absolute/Oh-My-OOP/dist/index.js`라는 실행 경로를 명시하세요. 새 에이전트 프로세스에서도 Node.js와 해당 CLI에 접근할 수 있어야 합니다. npm 레지스트리의 동명 패키지를 자동 다운로드하는 `npx oh-my-oop`는 안내하지 않습니다.
+
+### 2. Skill 설치 — 대상 프로젝트에서 실행
+
+**현재 로컬 변경을 바로 사용하려면**, 대상 프로젝트로 이동한 후 로컬 저장소에서 설치하세요.
+
+```sh
+cd /absolute/my-project
+npx skills add /absolute/Oh-My-OOP --skill oh-my-oop -a claude-code -a codex
+```
+
+Claude Code와 Codex 양쪽에 같은 Skill을 설치합니다. 하나만 사용하면 해당 `-a`만 남기세요. 다른 에이전트는 `-a`를 생략해 대화형으로 선택하거나 Skills CLI의 지원 에이전트 ID를 지정하세요.
+
+```sh
+npx skills add /absolute/Oh-My-OOP --skill oh-my-oop
+```
+
+기본은 프로젝트 범위이고 개인 공용 설치는 `-g`를 추가합니다. 복사 설치를 원하면 `--copy`를 사용하세요. 로컬 저장소 없이 Skill만 설치하려면 GitHub 소스를 사용합니다. 코어 CLI 준비는 여전히 별도입니다.
+
+```sh
+npx skills add no1msh/Oh-My-OOP --skill oh-my-oop -a claude-code -a codex
+```
+
+설치 목록/업데이트/삭제는 Skills CLI로 관리합니다.
+
+```sh
+npx skills list
+npx skills update oh-my-oop
+npx skills remove oh-my-oop
+```
+
+로컬 경로 설치의 갱신은 해당 Skills CLI 버전의 안내를 따르세요. 원본 변경이 자동 동기화된다고 가정하지 마세요. 원격 소스 업데이트 역시 **Skill만 갱신**합니다. npm으로 설치한 코어는 `npm install -g oh-my-oop@latest`로 별도 갱신하고, 소스 설치는 저장소 갱신 후 다시 빌드하세요.
+
+### 3. 에이전트에서 사용
+
+“oh-my-oop Skill로 주문 객체의 책임 분배를 검토해줘. 대상 프로젝트는 /absolute/my-project야”라고 요청하세요. 호스트의 Skill 선택 UI/직접 호출 기능을 사용해도 됩니다.
+
+공통 Skill은 표준 name/description과 Markdown만 사용하며 호스트 전용 확장 문법이나 `runtime.json`에 의존하지 않습니다. 자동 설치 대상에 없는 에이전트도 표준 Skill 폴더를 읽고 CLI를 실행할 수 있다면 수동으로 연결할 수 있지만, 모든 에이전트에서의 동작을 보증하지는 않습니다.
+
+- Skill 설치만으로 CLI·의존성이 설치되거나 `.oop`가 초기화되지는 않습니다.
+- 셸 실행이 금지된 채팅 환경에서는 실행 코어를 사용할 수 없습니다. 원격/컨테이너 에이전트는 그 환경 안에 코어를 준비하세요.
+- 자체 `skill install --target` 명령은 제거했습니다. 예전에 자체 설치기로 설치했다면 **해당 oh-my-oop 폴더만** 백업한 뒤 Skills CLI로 다시 설치하세요. 기존 파일의 덮어쓰기/삭제 확인을 읽고 진행하세요.
+- 이전 `runtime.json` 경로는 새 Skill이 읽지 않습니다. PATH 또는 명시한 CLI 경로를 준비하세요.
+- 설치는 사용자의 선택입니다. 에이전트가 소프트웨어를 임의 설치하거나 권한을 우회하지 않도록 Skill에 명시했습니다.
+
+## B. MCP로 사용하기
+
+Skill 설치 없이 MCP 서버만 등록하면 됩니다. 다음은 npm 전역 설치 후 사용하는 `mcpServers` JSON 형식 예시입니다. 호스트별 설정 파일/형식은 해당 호스트 안내를 따르세요.
+
+```json
+{
+  "mcpServers": {
+    "oh-my-oop": {
+      "command": "oh-my-oop",
+      "args": ["mcp"],
+      "env": { "OOP_PROJECT_ROOT": "/absolute/my-project" }
+    }
+  }
+}
+```
+
+호스트가 PATH에서 CLI를 찾지 못하거나 소스로 설치했다면 `command`를 `node`, `args`를 `["/absolute/Oh-My-OOP/dist/index.js", "mcp"]`로 지정하세요. 프로젝트 로컬 npm 설치라면 위의 `node_modules` 경로를 사용합니다.
+
+인자 없이 실행해도 stdio MCP가 시작됩니다. 서버 로그는 stderr로 나갑니다. `oop_capabilities`와 `oop_describe`에서 연산과 입력 스키마를 확인할 수 있습니다. 서버를 변경/재빌드했다면 MCP 연결을 재시작하세요.
+
+## 제공하는 기능과 한계
+
+- 유스케이스, CRC 카드, 책임 배분, 객체 간 협력 저장
+- 여러 설계 대안·트레이드오프·재검토 질문
+- 저장된 설계 모델의 응집도·결합도·의존 방향 등 권고 검사
+- Mermaid 클래스 다이어그램, 이력과 Before/After 비교
+- 구현 검토에 사용할 설계 계약과 체크리스트
+
+`design_validate`는 **저장된 설계 모델**을 검사하지, 실제 Kotlin/Android 소스를 자동 분석하지 않습니다. `conformance_check`는 호스트 LLM이 허용된 실제 구현과 비교할 계약을 반환하며 자동 합격 판정이 아닙니다. Finding은 권고이고 둘 이상의 remedy를 제공합니다.
+
+동일한 프로젝트 루트라면 Skill/CLI와 MCP가 같은 `.oop`를 읽습니다. 대화·로그인은 이전하지 않으며 여러 에이전트의 동시 편집 잠금을 제공하지 않습니다.
+
+## CLI 직접 사용
+
+```sh
+node dist/index.js system capabilities
+node dist/index.js oop init --root /absolute/my-project
+node dist/index.js oop design_validate --root /absolute/my-project
+echo '{"command":"oop","operation":"class_upsert"}' | node dist/index.js system describe --input -
+```
+
+`oop <operation> --input FILE` 또는 `--input -`로 JSON 객체를 전달합니다. JSON에는 `action`을 넣지 않습니다. `--root`는 대상 프로젝트이며 생략 시 `OOP_PROJECT_ROOT`, 호환 별칭 `ARCH_PROJECT_ROOT`, 현재 디렉터리 순으로 결정합니다.
+
+## 개발과 제품 범위
+
+새 디렉터리에 소스만 복사해 `npm ci` → 빌드 → 테스트 → tarball 설치를 검증할 수 있습니다. 설치된 패키지의 CLI/MCP와 Claude Code·Codex용 Skill 복사 설치도 확인합니다. npm 네트워크 접근이 필요하며 전역 설치·모델 호출·배포는 하지 않습니다. 새 폴더 검사이지 새 OS/VM 검사는 아닙니다.
+
+```sh
+node scripts/check-package-install.mjs --execute
+```
+
+```sh
+npm run build
+npm test
+```
+
+실제 외부 설치 CLI까지 확인하려면 다음 검사를 별도로 실행하세요. `skills@1.7.0`을 npm에서 가져올 수 있으며 임시 프로젝트에서 Claude Code/Codex의 복사·심볼릭 링크 설치와 MCP 없는 코어 실행을 검사합니다. 텔레메트리는 끄고 실행하며 테스트 산출물 경로를 출력합니다. 실제 에이전트 추론이나 UI의 Skill 선택 품질을 검증하는 것은 아닙니다.
+
+```sh
+node scripts/check-skills-distribution.mjs --execute
+```
+
+실제 로그인된 Claude Code/Codex가 Skill을 읽고 CLI를 사용하는 테스트도 별도로 실행할 수 있습니다. 두 CLI가 설치·로그인되어 있어야 하며 **모델 사용량/비용이 발생할 수 있습니다**. 새 `Downloads/oh-my-oop-live-*` 프로젝트에서 Claude가 설계를 저장하고 Codex가 읽기·검증하며, 프롬프트/도구 로그/전후 상태를 그 폴더에 보존합니다. 기본 설정 일부를 테스트 세션에서 제외하므로 기존 MCP 연결이나 그래픽 UI 테스트와는 다릅니다. 재실행은 필요할 때만 하세요.
+
+```sh
+node scripts/check-live-agents.mjs --execute
+```
+
+이 제품은 OOP 전용입니다. 아키텍처 워커·Kotlin 분석·JEV 실험은 별도 하네스로 분리했으며 `arch_*`, project/task/review/semantic 명령은 제공하지 않습니다. Skill 배포는 외부 `npx skills`를 사용하며 자체 설치기는 제공하지 않습니다.
+
+[제품 경계](SCOPE.md) · [코어/MCP 구조](MCP_STRUCTURE.md) · [개발 가이드](CLAUDE.md) · [공통 Skill](skills/oh-my-oop/SKILL.md)

package/SCOPE.md

@@ -0,0 +1,27 @@
+# OOP 제품 경계와 전달 방식 — 2026-09-24
+
+## 결정
+
+사용자가 **Skill + CLI** 또는 **MCP**를 선택한다. 두 경로는 `src/oop/commands.ts`의 같은 검증·저장 코드를 호출한다. `skills/oh-my-oop/SKILL.md`는 표준 Agent Skills 형식이며 특정 호스트의 확장 문법에 의존하지 않는다. Skill 배포·에이전트 선택은 외부 `npx skills`가 담당한다. 자체 설치기와 runtime.json 생성을 제거했으며 OOP 코어는 별도 빌드/실행한다. Skill 업데이트와 코어 업데이트도 별개다.
+
+| 선택 | 이 제품에서 얻는 것 | 부담 / 한계 |
+|---|---|---|
+| MCP | 구조화된 도구 입력, `.oop` 상태, 검사·다이어그램 코어 재사용. 새 하네스도 CLI/MCP로 호출 가능 | MCP 등록·호환성 테스트 유지 필요 |
+| Skill + CLI | 워크숍 순서를 필요할 때 읽고 셸에서 코어 실행. MCP 연결 불필요 | 호스트별 Skill 발견·권한 차이. 실행 코드와 상태 저장은 여전히 필요 |
+| 순수 Skill | 배포 파일이 적고 설명 중심 워크숍에 간단함 | 검사·저장·비교를 LLM 지시에 맡기거나 실행기를 다시 만들어야 함 |
+
+현재 가볍게 만들 부분은 프로토콜보다 제품 범위다. MCP를 유지한다고 특정 모델/API가 필요한 것은 아니다. 다만 어느 방식이 더 빠른지는 별도 비교하지 않았으며 속도 우위를 주장하지 않는다.
+
+공식 개념 근거: [MCP 서버 도구·리소스·프롬프트](https://modelcontextprotocol.io/docs/learn/server-concepts), [Agent Skills](https://agentskills.io/home). Skills도 스크립트를 포함할 수 있으므로 ‘Skill은 코드 실행 불가’라는 구분은 틀리다. 여기서는 절차 안내와 실행 코어의 책임을 구분한다.
+
+## 남긴 것
+
+`src/oop`, `domain`, `io`, `validate`, `tradeoff`, `render`, `prompts`, `resources`, OOP MCP 래퍼, 작은 CLI/명령 발견 기능. 새 OOP Skill은 CLI를 사용한다. OOP 관련 기존 수정·신규 규칙·프롬프트·lessons·발표 문서는 보존했다.
+
+## 분리한 것
+
+`src/architecture`, `src/runner`, `src/semantic`, 대응 MCP 도구와 테스트, `docs`, `benchmarks`, `integrations`, `examples`, 아키텍처 Skills/TypeSafe Skill과 lock. 새 하네스에서 실험 코드를 재검토해 채택한다. OOP 제품에는 JEV 호출이나 에이전트 실행기를 남기지 않는다.
+
+로컬 인수인계 위치: `/Users/moon/Downloads/architecture-migration/START-HERE.md`. 저장소 독자가 이 개인 경로에 접근할 수 있다고 가정하지 않는다. 외부 공개·업로드·새 저장소 생성은 하지 않았다.
+
+원본 파일/해시/이동 대상은 그 폴더의 `migration-manifest.json`, 이동 전 전체 작업 트리는 `reference-project`에 있다. `.git`, 의존성, 빌드 산출물, 실제 로컬 비밀값은 참조 스냅샷에서 제외했다. 원래 dirty 변경을 reset/checkout하지 않았다. 복구는 필요한 파일만 스냅샷과 비교 후 복사하며 현재 변경 전체를 덮어쓰지 않는다.

package/dist/application/discovery.d.ts

@@ -0,0 +1,133 @@
+import { z } from "zod";
+export declare const CapabilitiesInputSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+export declare const DescribeInputSchema: z.ZodObject<{
+    command: z.ZodEnum<["oop", "system"]>;
+    operation: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    command: "oop" | "system";
+    operation: string;
+}, {
+    command: "oop" | "system";
+    operation: string;
+}>;
+export declare function capabilities(): {
+    schema_version: number;
+    product: string;
+    model: {
+        required: null;
+        skill_required: boolean;
+    };
+    interfaces: {
+        skill: {
+            installer: string;
+            install: string;
+            core_setup: string;
+            invokes: string;
+            mcp_required: boolean;
+        };
+        mcp: {
+            transport: string;
+            argv: string[];
+            skill_required: boolean;
+        };
+    };
+    operations: {
+        command: string;
+        operation: string;
+        cli: {
+            argv: string[];
+        };
+        mcp: {
+            tool: string;
+            exposed: boolean;
+            arguments: string;
+        };
+        side_effect: string;
+    }[];
+    state: {
+        durable: string[];
+        scope: string;
+    };
+    limits: string[];
+};
+export declare function describeOperation(input: unknown): {
+    input_schema: import("zod-to-json-schema").JsonSchema7Type & {
+        $schema?: string | undefined;
+        definitions?: {
+            [key: string]: import("zod-to-json-schema").JsonSchema7Type;
+        } | undefined;
+    };
+    validation: string;
+    command: string;
+    operation: string;
+    cli: {
+        argv: string[];
+    };
+    mcp: {
+        tool: string;
+        exposed: boolean;
+        arguments: string;
+    };
+    side_effect: string;
+    schema_version: number;
+};
+export declare function systemCommand(action: string, input: unknown): {
+    schema_version: number;
+    product: string;
+    model: {
+        required: null;
+        skill_required: boolean;
+    };
+    interfaces: {
+        skill: {
+            installer: string;
+            install: string;
+            core_setup: string;
+            invokes: string;
+            mcp_required: boolean;
+        };
+        mcp: {
+            transport: string;
+            argv: string[];
+            skill_required: boolean;
+        };
+    };
+    operations: {
+        command: string;
+        operation: string;
+        cli: {
+            argv: string[];
+        };
+        mcp: {
+            tool: string;
+            exposed: boolean;
+            arguments: string;
+        };
+        side_effect: string;
+    }[];
+    state: {
+        durable: string[];
+        scope: string;
+    };
+    limits: string[];
+} | {
+    input_schema: import("zod-to-json-schema").JsonSchema7Type & {
+        $schema?: string | undefined;
+        definitions?: {
+            [key: string]: import("zod-to-json-schema").JsonSchema7Type;
+        } | undefined;
+    };
+    validation: string;
+    command: string;
+    operation: string;
+    cli: {
+        argv: string[];
+    };
+    mcp: {
+        tool: string;
+        exposed: boolean;
+        arguments: string;
+    };
+    side_effect: string;
+    schema_version: number;
+};