maskweaver 0.7.20 → 0.7.22

package/assets/commands/weave-craft.md

@@ -17,9 +17,20 @@ AI가 자동으로 검증 루프를 돌리고, 완료되면 유저에게 전달
 - **Global Knowledge**: 과거 트러블슈팅 경험 검색/기록
 - **Verify**: 다층 AI 자동 검증 시스템
 
----
-
-## 사전 조건: 활성 플랜 확인
+---
+
+## 핵심 원칙: 요청받은 Phase만 구현
+
+> **⚠️ CRITICAL: `/weave-craft`는 지정된 Phase의 작업만 수행합니다. 다른 Phase의 작업이나 계획에 없는 범위 밖 구현은 절대 수행하지 않습니다.**
+
+- 플랜 파일에 정의된 해당 Phase의 `checklist`와 `tasks` 항목만 구현합니다.
+- 다음 Phase에 해당하는 작업을 미리 구현하지 않습니다.
+- Phase 범위에 명시되지 않은 기능, 파일, 설정을 추가하지 않습니다.
+- 범위 밖 작업이 필요하다고 판단되면, 구현하지 않고 유저에게 알려 플랜 수정을 제안합니다.
+
+---
+
+## 사전 조건: 활성 플랜 확인
 
 실행 전 반드시:
 
@@ -77,18 +88,53 @@ AI가 자동으로 검증 루프를 돌리고, 완료되면 유저에게 전달
 
 ---
 
-## Step 0: LOAD PLAN
-
-```yaml
-# 1. state.yaml에서 활성 플랜 확인
-active_plan: "emotion-diary"
-
-# 2. plans/emotion-diary.yaml에서 Phase 정보 로드
-# 3. Phase 상태가 pending 또는 in_progress인지 확인
-# 4. completed인 Phase를 재실행하려면 유저에게 확인
-```
-
----
+## Step 0: LOAD PLAN
+
+```yaml
+# 1. state.yaml에서 활성 플랜 확인
+active_plan: "emotion-diary"
+
+# 2. plans/emotion-diary.yaml에서 Phase 정보 로드
+# 3. Phase 상태가 pending 또는 in_progress인지 확인
+# 4. completed인 Phase를 재실행하려면 유저에게 확인
+```
+
+### YAML 읽기 실패 시 자동 수복
+
+플랜 파일(`state.yaml` 또는 `plans/*.yaml`)을 읽었을 때 YAML 파싱 에러가 발생하면, 자동 수복을 시도합니다.
+
+**일반적인 깨짐 패턴과 수복 방법**:
+
+| 깨짐 패턴 | 증상 | 수복 방법 |
+|-----------|------|----------|
+| 들여쓰기 불일치 | `bad indentation` 에러 | 들여쓰기를 2-space 기준으로 정규화 |
+| 탭 문자 혼입 | `tab character` 에러 | 탭 → 2 spaces 변환 |
+| 따옴표 미닫힘 | `unexpected end of stream` | 열린 따옴표 찾아서 닫기 |
+| 중복 키 | `duplicate key` 에러 | 나중에 나온 값 유지, 중복 제거 |
+| 빈 값/null 깨짐 | `null` 대신 빈 문자열 | `null` 또는 적절한 기본값으로 복원 |
+| 잘린 파일 | 파일이 중간에 끊김 | 마지막 완전한 블록까지 복원 후 유저 알림 |
+
+```
+YAML 읽기 수복 절차:
+1. Read(yaml_path) → 파일 내용 로드
+2. YAML 파싱 시도
+   ├─ 성공 → 정상 진행
+   └─ 실패 → 수복 시작
+3. 수복 시도:
+   a. 파일 원본 내용을 보존 (백업용 변수에 저장)
+   b. 일반적인 깨짐 패턴 자동 교정 (위 표 참고)
+   c. 교정된 내용으로 다시 YAML 파싱 시도
+      ├─ 성공 → 교정된 내용으로 파일 덮어쓰기 + 유저에게 수복 사실 알림
+      └─ 실패 → 4단계로
+4. 수복 불가 시:
+   a. 유저에게 "YAML 파일이 심각하게 손상됨" 알림
+   b. 원본 내용을 그대로 출력하여 유저가 직접 수정할 수 있게 제공
+   c. `/weave-design`으로 플랜 재생성 제안
+```
+
+> **주의**: 수복 시 원본 데이터를 최대한 보존합니다. 확실하지 않은 값은 추측하지 않고, 유저에게 확인을 요청합니다.
+
+---
 
 ## Expert Summoning Strategy for Execution (Core)
 
@@ -235,28 +281,77 @@ Stuck on performance issue:
 
 ---
 
-## Step 4: UPDATE PLAN
-
-Phase 완료 시 플랜 파일을 업데이트합니다:
-
-```yaml
-# .opencode/weave/plans/{active_plan}.yaml 내 해당 Phase 업데이트:
-phases:
-  - id: "P1"
-    status: "completed"         # pending → in_progress → completed
-    started_at: "2026-02-06T10:30:00"
-    completed_at: "2026-02-06T13:00:00"
-    masks_used:
-      - name: "kent-beck"
-        tasks: 2
-        effectiveness: 0.9
-      - name: "dan-abramov"
-        tasks: 1
-        effectiveness: 0.85
-    retry_count: 1
-    issues:
-      - "JSON 직렬화 오류 → useEffect 의존성 추가로 해결"
-```
+## Step 4: UPDATE PLAN
+
+Phase 완료 시 플랜 파일을 업데이트합니다:
+
+```yaml
+# .opencode/weave/plans/{active_plan}.yaml 내 해당 Phase 업데이트:
+phases:
+  - id: "P1"
+    status: "completed"         # pending → in_progress → completed
+    started_at: "2026-02-06T10:30:00"
+    completed_at: "2026-02-06T13:00:00"
+    masks_used:
+      - name: "kent-beck"
+        tasks: 2
+        effectiveness: 0.9
+      - name: "dan-abramov"
+        tasks: 1
+        effectiveness: 0.85
+    retry_count: 1
+    issues:
+      - "JSON 직렬화 오류 → useEffect 의존성 추가로 해결"
+```
+
+### 플랜 업데이트 후 검증 (필수)
+
+플랜 파일 업데이트 후, 반드시 다음을 확인합니다:
+
+1. **Phase 상태 반영 확인**: 해당 Phase의 `status`가 `completed`로 변경되었는지 검증
+2. **타임스탬프 기록 확인**: `started_at`과 `completed_at`이 올바르게 기록되었는지 검증
+3. **다른 Phase 무변경 확인**: 실행하지 않은 Phase들의 상태가 변경되지 않았는지 검증
+4. **검증 실패 시**: 유저에게 오류를 알리고 플랜 파일 재업데이트 시도
+
+```
+검증 절차:
+1. Read(".opencode/weave/plans/{active_plan}.yaml") → 전체 플랜 파일 읽기
+2. 해당 Phase의 status == "completed" 확인
+3. started_at, completed_at 값 존재 확인
+4. 다른 Phase들의 status가 원래 값 그대로인지 확인
+5. 모두 정상이면 → 유저 핸드오프 진행
+6. 하나라도 실패하면 → 오류 보고 및 재시도
+```
+
+### YAML 쓰기 시 자동 수복
+
+플랜 파일을 업데이트한 후 다시 읽어 검증할 때 YAML 파싱 에러가 발생하면, 업데이트 과정에서 YAML이 깨진 것입니다. 이 경우 자동 수복을 수행합니다.
+
+```
+YAML 쓰기 수복 절차:
+1. 플랜 파일 업데이트 (Write)
+2. 업데이트된 파일 다시 읽기 (Read)
+3. YAML 파싱 시도
+   ├─ 성공 → 정상 진행 (검증 계속)
+   └─ 실패 → 쓰기 수복 시작
+4. 쓰기 수복:
+   a. 업데이트 전 원본 플랜 내용을 기반으로 재구성
+   b. 변경해야 할 Phase 필드만 정확히 반영하여 YAML을 처음부터 다시 생성
+   c. 재생성된 YAML로 파일 덮어쓰기
+   d. 다시 읽어서 파싱 검증
+      ├─ 성공 → 유저에게 "YAML 수복 후 정상 저장됨" 알림
+      └─ 실패 → 5단계로
+5. 재수복 실패 시:
+   a. 유저에게 "플랜 파일 업데이트 중 YAML 손상 발생" 알림
+   b. 정상적인 원본 내용 + 이번 Phase 변경사항을 텍스트로 출력
+   c. 유저가 직접 확인 후 수동 저장하도록 안내
+```
+
+**쓰기 수복 시 핵심 규칙**:
+- 업데이트 전 원본 파일 내용을 항상 메모리에 보관해 둡니다 (롤백 대비).
+- YAML을 부분 편집(텍스트 치환)하지 않고, 전체 구조를 파악한 뒤 완전한 YAML로 재생성합니다.
+- 특수문자가 포함된 문자열 값은 반드시 따옴표로 감쌉니다.
+- 재생성 시 원본의 Phase 순서와 필드 순서를 유지합니다.
 
 ---
 

package/assets/commands/weave-design.md

@@ -256,10 +256,40 @@ Phase 1을 시작하려면:
 
 ---
 
-## 주의사항
-
-1. **Phase는 작게**: 큰 Phase는 분할
-2. **복잡한 분석은 위임**: Task(dummy-human)으로 전문가 위임
-3. **테스트 가능해야**: 각 Phase 끝에 유저가 확인할 수 있어야
-4. **아키텍처는 유연하게**: "변경 가능"을 명시
-5. **플랜 이름은 kebab-case**: 파일명이 되므로 영문 소문자, 하이픈만 사용
+## 핵심 원칙: 계획만 수립, 구현 금지
+
+> **⚠️ CRITICAL: `/weave-design`은 계획 파일(.yaml)만 생성합니다. 코드 구현, 파일 생성, 프로젝트 셋업 등 실제 구현 작업은 절대 수행하지 않습니다.**
+
+- 이 커맨드의 산출물은 오직 `.opencode/weave/plans/{plan-name}.yaml` 파일과 `state.yaml` 업데이트뿐입니다.
+- 코드 작성, 디렉토리 생성, 패키지 설치 등 구현에 해당하는 모든 행위는 `/weave-craft` 단계에서 수행합니다.
+- Phase 내부의 `tasks`는 계획 항목으로만 기록하고, 실행하지 않습니다.
+
+---
+
+## 완료 후 검증 (필수)
+
+플랜 파일 생성 후, 반드시 다음을 확인합니다:
+
+1. **플랜 파일 존재 확인**: `.opencode/weave/plans/{plan-name}.yaml` 파일이 실제로 존재하는지 검증
+2. **state.yaml 반영 확인**: `active_plan` 값이 새 플랜 이름으로 올바르게 설정되었는지 검증
+3. **검증 실패 시**: 유저에게 오류를 알리고 재생성 시도
+
+```
+검증 절차:
+1. Read(".opencode/weave/plans/{plan-name}.yaml") → 파일 존재 확인
+2. Read(".opencode/weave/state.yaml") → active_plan 값 확인
+3. 둘 다 정상이면 → 완료 메시지 출력
+4. 하나라도 실패하면 → 오류 보고 및 재시도
+```
+
+---
+
+## 주의사항
+
+1. **Phase는 작게**: 큰 Phase는 분할
+2. **복잡한 분석은 위임**: Task(dummy-human)으로 전문가 위임
+3. **테스트 가능해야**: 각 Phase 끝에 유저가 확인할 수 있어야
+4. **아키텍처는 유연하게**: "변경 가능"을 명시
+5. **플랜 이름은 kebab-case**: 파일명이 되므로 영문 소문자, 하이픈만 사용
+6. **구현 금지**: 이 커맨드에서는 계획 파일 생성 외 어떤 코드/파일도 만들지 않음
+7. **검증 필수**: 플랜 파일 생성 후 반드시 파일 존재와 state.yaml 반영을 확인

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maskweaver",
-  "version": "0.7.20",
+  "version": "0.7.22",
   "description": "AI Expert Persona System - Give your AI coding assistant expert personalities (가면술사)",
   "type": "module",
   "main": "./dist/index.js",