maskweaver 0.8.2 → 0.8.4

package/README.ko.md

@@ -24,9 +24,10 @@
 - **전문가 페르소나 (Masks)**: 전설적인 개발자들의 철학을 담은 표준 YAML 프로필.
 - **스마트 위임**: OpenCode에 최적화된 멀티 에이전트 워크플로우.
 - **프로젝트 메모리**: 코드베이스 전체에 대한 하이브리드 의미론적 검색.
-- **🆕 Weave 워크플로우**: AI 자체 검증이 포함된 Phase 기반 개발.
-
----
+- **🆕 Weave 워크플로우**: AI 자체 검증이 포함된 Phase 기반 개발.
+- **🔗 GDC 통합**: Graph-Driven Codebase 지원으로 리서치 품질 향상 및 설계 시점 검증 게이트 추가.
+
+---
 
 ## 왜 Maskweaver인가요?
 
@@ -165,7 +166,7 @@ profile:
 
 **Phase 기반 개발** — "AI가 검증하고, 유저가 확인한다"
 
-Weave는 Maskweaver의 핵심 워크플로우입니다. 작업을 테스트 가능한 Phase로 나누고, 전문가 마스크를 자동 선택하며, 유저에게 전달하기 전에 자체 검증 루프를 실행합니다.
+Weave는 Maskweaver의 핵심 워크플로우입니다. 작업을 테스트 가능한 Phase로 나누고, 전문가 마스크를 자동 선택하며, 유저 전달 전 구조화된 검증 단계를 제공합니다.
 
 #### 명령어
 
@@ -176,10 +177,10 @@ Weave는 Maskweaver의 핵심 워크플로우입니다. 작업을 테스트 가
 | `/weave prepare [docs]` | (수동 경로) research + baseline spec + phase plan 생성 (큰 계획은 자동 분할) |
 | `/weave refine-plan` | `tasks/plan-notes.md` 지시문을 active plan에 반영 |
 | `/weave approve-plan` | 구현 전 사람이 계획 승인(게이트) |
-| `/weave flow [docs]` | (권장) 원커맨드 경로: prepare -> approve-plan gate -> craft auto-loop + auto finalize |
+| `/weave flow [docs]` | (권장) 원커맨드 경로: prepare -> auto-approve -> craft -> verify -> finalize |
 | `/weave spec [docs]` | baseline spec만 생성 (선택) |
 | `/weave design [docs]` | 요구사항 분석 → Phase 계획 생성 (`/weave plan`은 별칭/호환, 큰 계획은 자동 분할) |
-| `/weave craft [P#]` | Phase 실행 계획 생성/실행 + 자동 task loop + 목표 체크 + auto finalize |
+| `/weave craft [P#]` | Phase 실행 컨텍스트/가이드 생성 |
 | `/weave verify` | 빌드/테스트 검증 실행 (자동 감지) |
 | `/weave worktree ...` | git worktree 기반 병렬 작업 관리 |
 | `/weave status` | 프로젝트 진행 상황 및 통계 확인 |
@@ -193,7 +194,7 @@ Weave는 Maskweaver의 핵심 워크플로우입니다. 작업을 테스트 가
 0. INIT (1회): /weave init
        ↓
 1. 원커맨드(권장): /weave flow docs/
-    - 실행: prepare -> approve-plan gate -> craft auto-loop
+    - 실행: prepare -> auto-approve -> craft -> verify -> finalize
        ↓
    (또는 수동 경로)
        ↓
@@ -207,9 +208,9 @@ Weave는 Maskweaver의 핵심 워크플로우입니다. 작업을 테스트 가
     - craft 실행 전 필수 승인
        ↓
 5. CRAFT: /weave craft
-    - Phase 실행 계획 생성 + 자동 task loop 실행
-    - PASS/FAIL/재시도/re-plan은 craft 루프에서 처리
-    - 마지막에 phase 목표 체크 + full verify + 완료 처리를 자동 수행
+     - Phase 실행 계획과 다음 액션 안내 생성
+     - 구현/검증 후 approve-plan으로 phase 완료 처리
+     - `/weave verify`로 빌드/테스트 검증 가능
        ↓
 6. HANDOFF: 유저가 UX/의도 확인 후 다음 Phase로 진행
 ```
@@ -227,9 +228,43 @@ Weave는 Maskweaver의 핵심 워크플로우입니다. 작업을 테스트 가
 | 5️⃣ E2E Tests | 테스트 | **Playwright** |
 | 6️⃣ Screenshot | 시각 | Playwright / 브라우저 캡처 |
 | 7️⃣ API Check | API | `fetch` 헬스 체크 |
-| 8️⃣ A11y | 접근성 | `axe-core` |
-
-#### 마스크 자동 선택
+| 8️⃣ A11y | 접근성 | `axe-core` |
+| 0️⃣ GDC Check | 설계 | `gdc check --machine` |
+
+#### GDC 통합 (Graph-Driven Codebase)
+
+Weave는 [GDC](https://github.com/ulgerang/gdc)(Graph-Driven Codebase)와 통합되어 리서치 품질을 향상시키고 설계 시점 검증 게이트를 추가합니다:
+
+**리서치 강화:**
+- `.gdc` 워크스페이스 자동 감지
+- GDC `stats`, `graph`, `check` 결과를 `tasks/research.md`에 포함
+- 그래프 엣지 기반 의존성 영향 범위(Blast Radius) 분석
+- 기능 키워드와 매칭된 재사용 후보 노드
+- 새 보고서 섹션: `GDC Node Coverage`, `Dependency Blast Radius`, `Existing Spec vs Implementation Drift`, `Candidate Reuse Nodes`
+
+**Pre-Verify 게이트:**
+GDC가 감지되면 `weave verify`와 `weave flow`가 자동으로 실행:
+1. `gdc sync --machine` - 스펙과 구현 동기화
+2. `gdc check --machine` - 스펙/구현 일치성 검증
+
+GDC check의 블로킹 에러는 검증을 중단시킵니다(`strictVerify` 모드로 설정 가능).
+
+**설정** (`maskweaver.config.json`):
+```json
+{
+  "gdc": {
+    "enabled": "auto",
+    "strictVerify": false,
+    "autoSyncOnPrepare": true
+  }
+}
+```
+
+- `enabled`: `true` | `false` | `"auto"` (기본값: `.gdc` 디렉터리 자동 감지)
+- `strictVerify`: `true`면 GDC check 실패 시 검증 차단; `false`면 경고 후 계속 진행
+- `autoSyncOnPrepare`: `weave prepare` 시 `gdc sync` 실행
+
+#### 마스크 자동 선택
 
 AI가 각 작업에 가장 적합한 전문가를 자동으로 선택합니다:
 
@@ -333,14 +368,15 @@ import { MaskLoader } from 'maskweaver/core';
 import { WeaveOrchestrator, GlobalKnowledge } from 'maskweaver/weave';
 ```
 
-**모듈:**
-- `maskweaver/core` - 가면 로딩, 검증 (YAML/JSON)
-- `maskweaver/memory` - 임베딩 + 벡터 검색 (5개 프로바이더)
-- `maskweaver/context` - 기능 기반 작업 추적
-- `maskweaver/verify` - 교차 가면 코드 리뷰
-- `maskweaver/retrospect` - 세션 효과 분석
-- `maskweaver/weave` - Phase 기반 개발 워크플로우
-- `maskweaver/plugin` - OpenCode 플러그인 엔트리 포인트
+**모듈:**
+- `maskweaver/core` - 가면 로딩, 검증 (YAML/JSON)
+- `maskweaver/memory` - 임베딩 + 벡터 검색 (5개 프로바이더)
+- `maskweaver/context` - 기능 기반 작업 추적
+- `maskweaver/verify` - 교차 가면 코드 리뷰
+- `maskweaver/retrospect` - 세션 효과 분석
+- `maskweaver/weave` - Phase 기반 개발 워크플로우
+- `maskweaver/gdc` - GDC(Graph-Driven Codebase) 통합 유틸리티
+- `maskweaver/plugin` - OpenCode 플러그인 엔트리 포인트
 
 ---
 
@@ -360,7 +396,7 @@ import { WeaveOrchestrator, GlobalKnowledge } from 'maskweaver/weave';
 /weave flow docs/
 ```
 
-한 번에 `prepare -> approve-plan gate -> craft auto-loop`까지 실행합니다.
+한 번에 `prepare -> auto-approve -> craft -> verify -> finalize`까지 실행합니다.
 
 수동 happy path (research + spec + plan 한 번에):
 
@@ -415,47 +451,28 @@ AI 인사이트가 포함된 현대적 감정 일기 앱 구축
 /weave craft
 ```
 
-`/weave craft`는 실행 계획을 생성한 뒤 자동 task loop를 즉시 실행합니다(phase 미지정 시 다음 phase 자동 선택). 구현 반영 후 같은 명령을 다시 실행하면 이어서 진행됩니다.
+`/weave craft`는 phase 실행 컨텍스트를 생성합니다(phase 미지정 시 다음 phase 자동 선택). 구현 반영 후 같은 명령으로 계획을 다시 확인할 수 있습니다.
 
-### 4단계: Craft 루프 이어서 진행
+### 4단계: 구현 진행
 
 ```txt
 weave command=craft phaseId="P1"
-weave command=craft phaseId="P1" taskId="P1-T1"
+weave command=verify
 ```
 
-원커맨드로 계속 이어서 진행하려면:
+원커맨드로 이어서 진행하려면:
 
 ```txt
 weave command=flow
 ```
 
-### 5단계: 자동 완료 처리
+### 5단계: Phase 완료 처리
 
 ```txt
 weave command=verify
-weave command=craft
+weave command=approve-plan
 ```
 
-진행 상황 출력:
-```markdown
-### Task 진행 상황
-
-#### Task 1: EmotionButton 컴포넌트
-- [x] 마스크: 🧪 켄트 벡
-- [x] 테스트 작성
-- [x] 구현
-- [x] 검증 완료 ✅
-
-#### Task 2: 상태 관리
-- [x] 마스크: ⚛️ 댄 아브라모프
-- [x] 테스트 작성
-- [x] 구현
-- [ ] 검증 중 🔄 (재시도 2/5)
-  - 💡 유사 솔루션 발견: "React 상태 타이밍 이슈"
-  - 수정: useEffect 의존성 배열 추가
-```
-
 ### 6단계: 핸드오프 & 검증
 
 모든 검증이 통과되면:

package/README.md

@@ -24,9 +24,10 @@ While it can be used as a standalone library, it works great with OpenCode to ad
 - **Expert Personas (Masks)**: Standardized YAML profiles for legendary developers.
 - **Smart Delegation**: Multi-agent workflows optimized for OpenCode.
 - **Project Memory**: Hybrid semantic search for your entire codebase.
-- **🆕 Weave Workflow**: Phase-driven development with AI self-verification.
-
----
+- **🆕 Weave Workflow**: Phase-driven development with AI self-verification.
+- **🔗 GDC Integration**: Graph-Driven Codebase support for enhanced research and design-time verification gates.
+
+---
 
 ## Why Maskweaver?
 
@@ -184,7 +185,7 @@ Smart subagents for cost-efficient multi-agent workflows:
 
 **Phase-Driven Development** — "AI verifies, Human validates"
 
-Weave is Maskweaver's flagship workflow. It breaks work into testable phases, auto-selects expert masks, and runs self-verification loops before handing off to you.
+Weave is Maskweaver's flagship workflow. It breaks work into testable phases, auto-selects expert masks, and provides structured verification before handoff.
 
 #### Commands
 
@@ -195,10 +196,10 @@ Weave is Maskweaver's flagship workflow. It breaks work into testable phases, au
 | `/weave prepare [docs]` | (Manual path) Generate research + baseline spec + phase plan (auto-split if oversized) |
 | `/weave refine-plan` | Apply structured plan notes (`tasks/plan-notes.md`) to active plan |
 | `/weave approve-plan` | Explicit human approval gate before implementation |
-| `/weave flow [docs]` | (Recommended) One-command path: prepare -> approve-plan gate -> craft auto-loop + auto finalize |
+| `/weave flow [docs]` | (Recommended) One-command path: prepare -> auto-approve -> craft -> verify -> finalize |
 | `/weave spec [docs]` | Generate baseline spec only (optional) |
 | `/weave design [docs]` | Analyze requirements → Generate phase plan (`/weave plan` alias, auto-split if oversized) |
-| `/weave craft [P#]` | Generate/run execution plan + auto task loop + goal check + auto finalize |
+| `/weave craft [P#]` | Prepare phase execution context and guidance |
 | `/weave verify` | Run build/test verification (auto-detect) |
 | `/weave worktree ...` | Manage git worktrees for parallel work |
 | `/weave status` | View project progress and stats |
@@ -212,7 +213,7 @@ Weave is Maskweaver's flagship workflow. It breaks work into testable phases, au
 0. INIT (once): /weave init
        ↓
 1. ONE-COMMAND (recommended): /weave flow docs/
-    - runs: prepare -> approve-plan gate -> craft auto-loop
+    - runs: prepare -> auto-approve -> craft -> verify -> finalize
        ↓
    (or manual path)
        ↓
@@ -226,9 +227,9 @@ Weave is Maskweaver's flagship workflow. It breaks work into testable phases, au
     - required before craft execution
        ↓
 5. CRAFT: /weave craft
-     - Generates an execution plan + runs auto task loop
-     - PASS/FAIL/retry/re-plan are handled in the craft loop
-     - Final goal check + full verification + phase completion are automatic
+     - Generates an execution plan and next actions
+     - Implement/verify changes, then finalize with approve-plan
+     - Use `/weave verify` anytime for build/test checks
        ↓
 6. HANDOFF: You validate UX/intent and move to next phase
 ```
@@ -246,9 +247,43 @@ Before handing off to you, AI runs these verification layers:
 | 5️⃣ E2E Tests | Test | **Playwright** |
 | 6️⃣ Screenshot | Visual | Playwright / browser capture |
 | 7️⃣ API Check | API | `fetch` health checks |
-| 8️⃣ A11y | Accessibility | `axe-core` |
-
-#### Autonomous Mask Selection
+| 8️⃣ A11y | Accessibility | `axe-core` |
+| 0️⃣ GDC Check | Design | `gdc check --machine` |
+
+#### GDC Integration (Graph-Driven Codebase)
+
+Weave integrates with [GDC](https://github.com/ulgerang/gdc) (Graph-Driven Codebase) to enhance research quality and add design-time verification gates:
+
+**Research Enhancement:**
+- Automatic `.gdc` workspace detection
+- GDC `stats`, `graph`, and `check` results embedded in `tasks/research.md`
+- Dependency blast radius analysis from graph edges
+- Candidate reuse nodes matched against feature keywords
+- New report sections: `GDC Node Coverage`, `Dependency Blast Radius`, `Existing Spec vs Implementation Drift`, `Candidate Reuse Nodes`
+
+**Pre-Verify Gate:**
+When GDC is detected, `weave verify` and `weave flow` automatically run:
+1. `gdc sync --machine` - Sync specs with implementation
+2. `gdc check --machine` - Validate spec/implementation alignment
+
+Blocking errors from GDC check will halt verification (configurable via `strictVerify` mode).
+
+**Configuration** (`maskweaver.config.json`):
+```json
+{
+  "gdc": {
+    "enabled": "auto",
+    "strictVerify": false,
+    "autoSyncOnPrepare": true
+  }
+}
+```
+
+- `enabled`: `true` | `false` | `"auto"` (default: auto-detect from `.gdc` directory)
+- `strictVerify`: If `true`, GDC check failures block verification; if `false`, continues with warning
+- `autoSyncOnPrepare`: Run `gdc sync` during `weave prepare`
+
+#### Autonomous Mask Selection
 
 The AI automatically picks the best expert for each task:
 
@@ -352,14 +387,15 @@ import { MaskLoader } from 'maskweaver/core';
 import { WeaveOrchestrator, GlobalKnowledge } from 'maskweaver/weave';
 ```
 
-**Modules:**
-- `maskweaver/core` - Mask loading, validation (YAML/JSON)
-- `maskweaver/memory` - Embeddings + vector search (5 providers)
-- `maskweaver/context` - Feature-based work tracking
-- `maskweaver/verify` - Cross-mask code review
-- `maskweaver/retrospect` - Session effectiveness analysis
-- `maskweaver/weave` - Phase-driven development workflow
-- `maskweaver/plugin` - OpenCode plugin entry point
+**Modules:**
+- `maskweaver/core` - Mask loading, validation (YAML/JSON)
+- `maskweaver/memory` - Embeddings + vector search (5 providers)
+- `maskweaver/context` - Feature-based work tracking
+- `maskweaver/verify` - Cross-mask code review
+- `maskweaver/retrospect` - Session effectiveness analysis
+- `maskweaver/weave` - Phase-driven development workflow
+- `maskweaver/gdc` - GDC (Graph-Driven Codebase) integration utilities
+- `maskweaver/plugin` - OpenCode plugin entry point
 
 ---
 
@@ -379,7 +415,7 @@ Fastest path (one command):
 /weave flow docs/
 ```
 
-This runs `prepare -> approve-plan gate -> craft auto-loop` in one shot.
+This runs `prepare -> auto-approve -> craft -> verify -> finalize` in one shot.
 
 Manual happy path (research + spec + plan in one command):
 
@@ -434,13 +470,13 @@ Start with the first phase:
 /weave craft
 ```
 
-`/weave craft` returns an execution plan and immediately runs the auto task loop. Re-run `/weave craft` after implementation updates to continue the same phase.
+`/weave craft` returns execution context for the phase. Implement changes, then rerun `/weave craft` if you want to refresh the plan view.
 
-### Step 4: Continue the Craft Loop
+### Step 4: Continue Implementation
 
 ```txt
 weave command=craft phaseId="P1"
-weave command=craft phaseId="P1" taskId="P1-T1"
+weave command=verify
 ```
 
 One-command resume:
@@ -449,32 +485,13 @@ One-command resume:
 weave command=flow
 ```
 
-### Step 5: Auto Finalization
+### Step 5: Finalize the Phase
 
 ```txt
 weave command=verify
-weave command=craft
+weave command=approve-plan
 ```
 
-Progress output:
-```markdown
-### Task Progress
-
-#### Task 1: EmotionButton Component
-- [x] Mask: 🧪 Kent Beck
-- [x] Tests written
-- [x] Implementation
-- [x] Verified ✅
-
-#### Task 2: State Management
-- [x] Mask: ⚛️ Dan Abramov
-- [x] Tests written
-- [x] Implementation
-- [ ] Verifying 🔄 (retry 2/5)
-  - 💡 Similar solution found: "React state timing issue"
-  - Fix: Added useEffect dependency array
-```
-
 ### Step 6: Handoff & Validate
 
 When all verifications pass: