sentix 2.0.2 → 2.0.22

package/FRAMEWORK.md

@@ -216,6 +216,8 @@ tasks/.pre-fix-test-results.json — npm run test --json 결과
 > 에이전트는 Governor가 준 컨텍스트만 본다.
 > 에이전트는 결과를 Governor에게만 반환한다.
 > 에이전트끼리 직접 통신하지 않는다.
+> **메서드 수준 명세: docs/agent-methods.md (필수 준수)**
+> 아래는 입출력 요약이다. 각 에이전트의 메서드 실행 순서와 세부 규칙은 agent-methods.md를 따른다.
 
 ### planner
 

package/README.md

@@ -83,7 +83,17 @@ Governor라는 "총감독"이 있고, 6명의 "직원(에이전트)"이 있습
 npx sentix init
 ```
 
-이것만 하면 됩니다. 필요한 파일이 자동으로 만들어집니다.
+이것만 하면 **전부 자동으로** 처리됩니다:
+
+```
+npx sentix init
+  ↓ CLAUDE.md, .sentix/, tasks/, docs/ 생성
+  ↓ 기술 스택 자동 감지 (Node.js, Python, Go, Rust)
+  ↓ FRAMEWORK.md 등 프레임워크 파일 자동 동기화
+  ↓ git pre-commit hook 설치 (검증 게이트)
+  ↓ 설치 상태 자동 진단 (sentix doctor)
+  ↓ 완료
+```
 
 > **`npx` vs 글로벌 설치:**
 > - `npx sentix ...` — 설치 없이 바로 실행 (매번 `npx` 붙여야 함)
@@ -124,13 +134,14 @@ mkdir -p /path/to/your-project/tasks/tickets
 
 ### 설치 확인
 
+`sentix init`이 끝나면 자동으로 `doctor`가 실행됩니다. 모든 항목이 ✓ 이면 성공입니다.
+
+나중에 다시 확인하고 싶으면:
+
 ```bash
-cd /path/to/your-project
-npx sentix doctor
+sentix doctor
 ```
 
-모든 항목이 ✓ 이면 성공입니다.
-
 ---
 
 ## 사용 방법
@@ -565,6 +576,44 @@ A: 자동 감지: Node.js, Python, Go, Rust. 그 외 언어도 CLAUDE.md를 수
 A: 6개 하드 룰이 있습니다. 기존 기능 삭제 금지, 범위 밖 수정 금지, 테스트 삭제 금지 등.
 이 규칙은 AI도 무시할 수 없습니다.
 
+**Q: `sentix` 명령이 안 됩니다 ("용어가 인식되지 않습니다")**
+A: 글로벌 설치가 안 되어 있으면 매번 `npx`를 붙여야 합니다:
+```bash
+npx sentix doctor    # npx로 실행 (설치 없이)
+
+# 또는 글로벌 설치 후 npx 없이 사용:
+npm install -g sentix
+sentix doctor        # 바로 실행 가능
+```
+
+**Q: `sentix update`가 "source not found"로 전부 건너뛰기합니다**
+A: npm 패키지 버전이 오래된 경우입니다. 최신 버전으로 업데이트하세요:
+```bash
+npm cache clean --force
+npm install -g sentix@latest
+sentix --version     # 최신 버전 확인
+sentix update        # 다시 시도
+```
+
+**Q: `sentix doctor`에서 FRAMEWORK.md가 MISSING입니다**
+A: `sentix init`은 FRAMEWORK.md를 생성하지 않습니다. `sentix update`로 가져옵니다:
+```bash
+sentix update        # sentix 원본에서 FRAMEWORK.md 등 동기화
+```
+
+**Q: npm publish 시 403 Forbidden (2FA) 에러가 납니다**
+A: npm 계정에 2FA가 활성화되어 있으면 Granular Access Token이 필요합니다:
+1. npmjs.com → 프로필 → Access Tokens → Generate New Token
+2. Granular Access Token 선택, publish 권한 부여
+3. `npm publish --//registry.npmjs.org/:_authToken=YOUR_TOKEN`
+
+**Q: `sentix evolve`는 뭔가요?**
+A: sentix가 자기 자신의 코드를 분석하고 개선점을 찾는 명령입니다:
+```bash
+sentix evolve          # 분석만
+sentix evolve --auto   # 분석 + critical 이슈 자동 수정
+```
+
 ---
 
 ## 런타임 모드
@@ -615,10 +664,8 @@ sentix doctor   # → Runtime: engine, Provider: claude, API key: set
 ## 정리
 
 ```
-1. sentix init                     ← 설치 (1분)
-2. CLAUDE.md 기술 스택 확인           ← 확인 (1분)
-3. sentix doctor                   ← 검증 (10초)
-4. sentix run "하고 싶은 것"         ← 사용 (끝!)
+1. npx sentix init                 ← 설치 + 동기화 + 진단 (전부 자동, 1분)
+2. sentix run "하고 싶은 것"         ← 사용 (끝!)
 ```
 
 ---

package/docs/agent-methods.md

@@ -0,0 +1,436 @@
+# Agent Methods — 에이전트별 메서드 명세
+
+> FRAMEWORK.md의 에이전트 정의를 보완하는 메서드 수준 상세 명세.
+> 각 에이전트가 **어떤 단계를 어떤 순서로 수행하는지** 정의한다.
+> 아키텍처 원칙: [Anthropic Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents) 기반.
+
+---
+
+## 설계 원칙
+
+### 1. Generator-Evaluator 분리
+
+```
+생성자 (dev/dev-fix)와 평가자 (pr-review)는 완전히 분리된다.
+생성자는 품질 판단을 하지 않는다. 하드룰 자기 검증만 수행한다.
+평가자는 코드를 수정하지 않는다. 판정만 내린다.
+```
+
+### 2. 산출물 제약, 경로 자유 (Constrain Outputs, Free Paths)
+
+```
+planner는 WHAT(무엇을)과 WHERE(어디를)만 정의한다.
+HOW(어떻게)는 dev가 결정한다.
+planner가 구현 방법을 명세하면 틀릴 경우 하류에 cascade된다.
+```
+
+### 3. 회의적 평가자 (Skeptical Evaluator)
+
+```
+pr-review는 의도적으로 회의적으로 튜닝된다.
+에이전트는 자기 작업에 관대하다 — 별도 평가자를 엄격하게 만드는 것이 효과적이다.
+의심스러우면 REJECTED. 관대함보다 엄격함이 낫다.
+```
+
+### 4. 복잡도 기반 강도 조절 (Conditional Intensity)
+
+```
+평가자의 가치는 태스크가 모델의 단독 능력 경계를 넘을 때 가장 높다.
+low complexity  → 하드룰 체크만 (빠른 통과)
+mid complexity  → 하드룰 + 품질 기준 채점
+high complexity → 하드룰 + 품질 기준 + 실제 동작 검증
+```
+
+### 5. Sprint Contract (사전 합의)
+
+```
+구현 전에 생성자와 평가자가 "완료 조건"을 합의한다.
+planner가 티켓을 만들면 pr-review가 평가 가능성을 사전 검증한다.
+불명확한 기준은 구현 전에 교정된다 — 사후 논쟁을 방지한다.
+```
+
+### 6. 하네스 간소화 원칙
+
+```
+파이프라인의 모든 단계는 "모델이 혼자 못 하는 것"에 대한 가정이다.
+그 가정은 주기적으로 스트레스 테스트해야 한다.
+모델 능력이 충분해지면 단계를 생략할 수 있다.
+
+config.toml [harness] 섹션으로 제어:
+  skip_contract = false       # contract 단계 생략 여부
+  skip_review_on_low = true   # low complexity 리뷰 생략
+  evaluator_intensity = "auto" # auto: complexity에 따라 자동 조절
+```
+
+---
+
+## planner
+
+요청을 분석하고 실행 가능한 티켓으로 변환한다.
+**WHAT과 WHERE만 정의한다. HOW는 정의하지 않는다.**
+
+### Methods
+
+```
+planner.analyze()
+  → 요청 분류 (BUG / FEATURE / VERSION / GENERAL)
+  → 키워드 추출
+  → 유형별 파이프라인 결정
+
+planner.research()
+  → tasks/lessons.md 검색 — 동일/유사 패턴의 과거 실패
+  → tasks/patterns.md 검색 — 관련 사용자 행동 패턴
+  → 기존 티켓 검색 — 중복 방지
+
+planner.scope()
+  → 변경 범위 결정 (영향받는 파일/모듈 식별)
+  → SCOPE 정의: 어떤 파일이 변경 대상인가
+  → ACCEPTANCE 정의: 완료 조건은 무엇인가
+  ██ 금지: 구체적 구현 방법 명세 (함수명, 알고리즘, 라이브러리 선택 등) ██
+
+planner.estimate()
+  → COMPLEXITY 판정 (low / mid / high)
+  → 플래그 설정: DEPLOY_FLAG, SECURITY_FLAG, PARALLEL_HINT
+  → high → dev-swarm 권고 여부
+
+planner.emit()
+  → 티켓 생성 (tasks/tickets/)
+  → 티켓 필드: TICKET_ID, TITLE, SCOPE, ACCEPTANCE, COMPLEXITY, FLAGS
+  → tasks/tickets/index.json 업데이트
+```
+
+### 출력 스키마
+
+```
+TICKET_ID:      dev-044
+TITLE:          세션 만료 검증 추가
+TYPE:           feature
+SCOPE:          src/auth/**, __tests__/auth/**
+ACCEPTANCE:
+  - 세션 만료 시 401 반환
+  - 만료 시간 설정 가능
+  - 기존 인증 흐름 유지
+COMPLEXITY:     mid
+DEPLOY_FLAG:    true
+SECURITY_FLAG:  true
+PARALLEL_HINT:  null
+```
+
+### planner가 정의하면 안 되는 것
+
+```
+✗ "jwt.verify()를 사용하라"          → 구현 방법은 dev가 결정
+✗ "middleware를 express.use()로 등록" → 기술 디테일은 dev가 결정
+✗ "Redis에 세션을 저장하라"           → 저장 방식은 dev가 결정
+✗ "함수명은 checkExpiry로 하라"       → 네이밍은 dev가 결정
+```
+
+---
+
+## pr-review — Contract 단계 (dev 전)
+
+dev가 구현을 시작하기 전에, 티켓의 평가 가능성을 사전 검증한다.
+
+### Methods
+
+```
+pr-review.contract()
+  → 티켓의 ACCEPTANCE 기준 검토
+  → 각 기준이 검증 가능한가? (코드 리뷰로 판단할 수 있는가?)
+  → 각 기준이 명확한가? (해석의 여지가 없는가?)
+  → 불명확한 기준 발견 시:
+      → planner에게 피드백 반환
+      → 피드백 내용: 어떤 기준이, 왜 불명확한지, 어떻게 교정하면 되는지
+      → planner 재조정 후 다시 contract() 실행
+  → 모든 기준이 명확하면: CONTRACT_APPROVED 반환
+```
+
+### Contract 판단 기준
+
+```
+검증 가능 (PASS):
+  "세션 만료 시 401 반환"          → 테스트로 검증 가능
+  "기존 인증 흐름 유지"            → 기존 테스트 통과로 검증 가능
+  "만료 시간 설정 가능"            → 설정 파라미터 존재 여부로 검증 가능
+
+검증 불가 (FEEDBACK):
+  "코드가 깔끔해야 한다"           → 주관적, 기준 불명확
+  "성능이 좋아야 한다"             → 수치 기준 없음
+  "보안이 강화되어야 한다"          → 구체적 조건 없음
+```
+
+---
+
+## dev
+
+티켓의 ACCEPTANCE 조건을 충족하는 코드를 구현한다.
+**구현 방법은 dev가 자율적으로 결정한다.**
+
+### Methods
+
+```
+dev.snapshot()
+  → npm test 실행 → tasks/.pre-fix-test-results.json 저장
+  → 현재 테스트 상태 기록 (회귀 검증 기준선)
+
+dev.implement()
+  → SCOPE 내 파일만 수정
+  → ACCEPTANCE 조건 충족을 목표로 구현
+  → 구현 방법은 dev가 결정 (planner의 HOW 명세 없음)
+
+dev.test()
+  → 새 코드에 대한 테스트 작성
+  → npm test 실행
+  → 기존 테스트 + 새 테스트 모두 통과 확인
+
+dev.verify()
+  → 하드룰 자기 검증만 수행:
+    □ 변경 파일이 SCOPE 안에 있는가
+    □ 기존 export를 삭제하지 않았는가
+    □ 기존 테스트를 삭제/약화하지 않았는가
+    □ 순삭제가 50줄을 넘지 않는가
+    □ 기존 기능/핸들러를 삭제하지 않았는가
+  → 위반 발견 시: 스스로 수정 후 다시 verify()
+  ██ 품질 판단은 하지 않는다 — pr-review에 위임 ██
+
+dev.report()
+  → diff 요약 반환
+  → 테스트 결과 반환
+  → 변경 파일 목록 반환
+```
+
+---
+
+## pr-review — 평가 단계 (dev 후)
+
+dev의 결과물을 티켓 기준으로 평가한다.
+**의도적으로 회의적(skeptical)으로 판단한다.**
+
+### Methods
+
+```
+pr-review.diff()
+  → 전체 변경 내용 확인 (git diff)
+  → 변경 범위가 SCOPE 내인지 확인
+  → pre-fix snapshot과 비교하여 회귀 여부 파악
+
+pr-review.validate()
+  → 하드룰 검증 (결정론적 — verify-gates.js와 동일 기준)
+    □ SCOPE 준수
+    □ export 삭제 없음
+    □ 테스트 삭제 없음
+    □ 순삭제 50줄 이내
+    □ 기능/핸들러 삭제 없음
+  → 하나라도 위반 시: 즉시 REJECTED (grade() 진행 안 함)
+
+pr-review.grade()
+  → COMPLEXITY=low이면 생략 (하드룰 통과만으로 APPROVED)
+  → COMPLEXITY=mid/high이면 4가지 품질 기준 채점:
+
+    1. 정확성 (Correctness)
+       → 티켓의 ACCEPTANCE 조건을 모두 충족하는가?
+       → 엣지 케이스를 처리했는가?
+
+    2. 일관성 (Consistency)
+       → 기존 코드베이스의 패턴/컨벤션을 따르는가?
+       → 네이밍, 구조, 에러 처리 방식이 기존과 일치하는가?
+
+    3. 간결성 (Simplicity)
+       → 불필요한 추상화, 과도한 설계가 없는가?
+       → 가장 단순한 해결책인가?
+
+    4. 테스트 충실도 (Test Coverage)
+       → 새 코드에 대한 테스트가 있는가?
+       → 엣지 케이스를 테스트하는가, 표면적 테스트인가?
+
+  → 각 기준별 PASS / FAIL
+  → 하나라도 FAIL이면 REJECTED
+
+pr-review.calibrate()
+  → tasks/lessons.md에서 과거 놓친 이슈를 few-shot 예시로 참조
+  → "이전에 이런 패턴을 놓쳤다. 이번에도 확인하라"
+  → 자기 합리화 방지: "이슈를 발견했다면 절대 스스로 합리화하지 마라"
+
+pr-review.verdict()
+  → 최종 판정: APPROVED / REJECTED
+  → REJECTED 시: 구체적 사유 + 어떤 기준이 미달인지 명시
+  → APPROVED 시: NEEDS_DEPLOY 여부 판단
+```
+
+### 채점 기준 상세
+
+```
+┌──────────────┬─────────────────────────────────┬───────────────────────┐
+│ 기준         │ PASS 조건                        │ FAIL 예시             │
+├──────────────┼─────────────────────────────────┼───────────────────────┤
+│ 정확성       │ ACCEPTANCE 조건 100% 충족         │ 조건 하나 누락         │
+│ 일관성       │ 기존 패턴과 일치                   │ 새로운 컨벤션 도입      │
+│ 간결성       │ 불필요한 추상화 없음               │ 과도한 설계, 미사용 코드 │
+│ 테스트 충실도 │ 엣지 케이스 포함한 테스트           │ happy path만 테스트    │
+└──────────────┴─────────────────────────────────┴───────────────────────┘
+```
+
+### 복잡도별 리뷰 강도
+
+```
+COMPLEXITY=low:
+  validate() → verdict()
+  grade() 생략 — 하드룰 통과만으로 충분
+
+COMPLEXITY=mid:
+  validate() → grade() → calibrate() → verdict()
+  4가지 품질 기준 전체 채점
+
+COMPLEXITY=high:
+  validate() → grade() → calibrate() → verdict()
+  4가지 품질 기준 + 실제 동작 검증 (Playwright 등 해당 시)
+```
+
+---
+
+## dev-fix
+
+pr-review 또는 security가 발견한 이슈를 수정한다.
+**LESSON_LEARNED 기록이 필수다.**
+
+### Methods
+
+```
+dev-fix.diagnose()
+  → 이슈 원인 분석
+  → pr-review의 REJECTED 사유 또는 security findings 참조
+  → Governor 교차 판단이 있으면 함께 참조
+  → 원인이 SCOPE 밖에 있으면 Governor에게 "SCOPE 확장 필요" 반환
+
+dev-fix.fix()
+  → SCOPE 내 코드 수정
+  → 이슈와 무관한 파일은 절대 수정하지 않음
+
+dev-fix.test()
+  → npm test 실행
+  → pre-fix snapshot 대비 회귀 없음 확인
+  → 수정한 이슈에 대한 테스트 추가/보강
+
+dev-fix.learn()
+  → LESSON_LEARNED 작성 (필수 — 생략 불가)
+  → tasks/lessons.md에 추가
+  → 형식: 날짜 + 이슈 요약 + 근본 원인 + 교훈
+  → 동일 패턴 3회 반복 감지 시 severity 자동 승격
+
+dev-fix.report()
+  → 수정 diff 반환
+  → 테스트 결과 반환
+  → LESSON_LEARNED 내용 반환
+```
+
+---
+
+## security
+
+전체 코드베이스를 읽기 전용으로 스캔한다.
+
+### Methods
+
+```
+security.scan()
+  → 전체 코드베이스 보안 분석
+  → 이전 tasks/security-report.md와 비교 (regression 확인)
+
+security.classify()
+  → 발견 항목별 severity 분류 (critical / warning / suggestion)
+  → false positive 필터링
+
+security.report()
+  → tasks/security-report.md 생성/업데이트
+  → VERDICT: PASSED / NEEDS_FIX
+  → NEEDS_FIX 시: 각 finding의 severity + 위치 + 설명
+```
+
+---
+
+## roadmap
+
+사이클 전체 이력을 분석하여 다음 계획을 수립한다.
+
+### Methods
+
+```
+roadmap.analyze()
+  → 이번 사이클의 요청, 티켓, 결과, 이슈, 리포트 종합 분석
+  → tasks/lessons.md에서 반복 패턴 식별
+  → tasks/patterns.md에서 트렌드 파악
+
+roadmap.plan()
+  → 즉시 / 단기 / 장기 계획 수립
+  → 다음 티켓 초안 작성
+
+roadmap.emit()
+  → tasks/roadmap.md 생성/업데이트
+```
+
+---
+
+## 전체 파이프라인 흐름 (Methods 기반)
+
+```
+사용자 요청
+  │
+  ▼
+planner.analyze() → research() → scope() → estimate() → emit()
+  │                                                        │
+  │  티켓 생성                                               │
+  ▼                                                        │
+pr-review.contract()  ◄─────────────────────────────────────┘
+  │
+  │  CONTRACT_APPROVED?
+  │  ├─ NO  → planner에게 피드백 → planner.scope() 재실행
+  │  └─ YES → 다음 단계
+  ▼
+dev.snapshot() → implement() → test() → verify() → report()
+  │
+  │  [검증 게이트: verify-gates.js]
+  ▼
+pr-review.diff() → validate() → grade()* → calibrate() → verdict()
+  │                               (* low면 생략)
+  │  APPROVED?
+  │  ├─ NO  → dev-fix.diagnose() → fix() → test() → learn() → report()
+  │  │        → pr-review 재실행
+  │  └─ YES → 다음 단계
+  ▼
+[DEPLOY_FLAG?] → devops
+  │
+  ▼
+[SECURITY_FLAG?] → security.scan() → classify() → report()
+  │                  │
+  │                  │  NEEDS_FIX? → dev-fix → pr-review → (반복)
+  ▼
+roadmap.analyze() → plan() → emit()
+  │
+  ▼
+[완료: 버전 범프 + lessons 업데이트 + 최종 보고]
+```
+
+---
+
+## config.toml 하네스 설정
+
+```toml
+[harness]
+# 주기적으로 재검토: 모델 능력 향상 시 단계 생략 가능
+skip_contract = false        # true: contract 단계 생략 (planner 신뢰도 높을 때)
+skip_review_on_low = true    # true: low complexity는 하드룰만 체크
+evaluator_intensity = "auto" # "auto" | "full" | "minimal"
+                             # auto: complexity에 따라 자동 조절
+                             # full: 항상 전체 채점
+                             # minimal: 항상 하드룰만
+```
+
+---
+
+## 참조
+
+- FRAMEWORK.md — 에이전트 정의, 5-Layer 아키텍처
+- docs/governor-sop.md — 7단계 파이프라인 상세
+- docs/agent-scopes.md — 에이전트별 파일 접근 범위
+- docs/severity.md — severity 분류 + 재시도 로직
+- src/lib/verify-gates.js — 하드룰 결정론적 검증 코드

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentix",
-  "version": "2.0.2",
+  "version": "2.0.22",
   "description": "Autonomous multi-agent DevSecOps pipeline CLI",
   "type": "module",
   "bin": {

package/src/commands/init.js

@@ -19,7 +19,15 @@ registerCommand('init', {
 
     // ── 1. CLAUDE.md ────────────────────────────────
     if (ctx.exists('CLAUDE.md')) {
-      ctx.warn('CLAUDE.md already exists — skipping');
+      // CLAUDE.md가 이미 있지만 Sentix Governor 지시문이 없으면 주입
+      const existing = await ctx.readFile('CLAUDE.md');
+      if (!existing.includes('Sentix Governor') && !existing.includes('sentix') && !existing.includes('SENTIX')) {
+        const directive = generateGovernorDirective();
+        await ctx.writeFile('CLAUDE.md', existing + '\n' + directive);
+        ctx.success('CLAUDE.md updated — Sentix Governor directive injected');
+      } else {
+        ctx.warn('CLAUDE.md already has Sentix directives — skipping');
+      }
     } else {
       const claudeTemplate = `# CLAUDE.md — Sentix Governor 실행 지침
 
@@ -294,18 +302,39 @@ type: # api | library | framework | service
     }
 
     // ── Done ────────────────────────────────────────
+    // init 완료 후 자동으로 update 실행 (FRAMEWORK.md 등 동기화)
+    ctx.log('\n--- Syncing framework files ---\n');
+    try {
+      const { getCommand } = await import('../registry.js');
+      const updateCmd = getCommand('update');
+      if (updateCmd) {
+        await updateCmd.run([], ctx);
+      }
+    } catch {
+      ctx.warn('Auto-update skipped (run manually: sentix update)');
+    }
+
     ctx.log('\n=== Sentix initialized ===');
     ctx.log('');
     if (techStack.detected) {
       ctx.success(`Detected: ${techStack.runtime} / ${techStack.packageManager}${techStack.framework !== '# 프로젝트에 맞게 설정' ? ' / ' + techStack.framework : ''}`);
     }
-    ctx.log('Next steps:');
-    ctx.log('  1. Edit CLAUDE.md → 기술 스택을 프로젝트에 맞게 확인');
+
+    // init 끝에 자동으로 doctor 실행
+    ctx.log('\n--- Health Check ---\n');
+    try {
+      const { getCommand } = await import('../registry.js');
+      const doctorCmd = getCommand('doctor');
+      if (doctorCmd) {
+        await doctorCmd.run([], ctx);
+      }
+    } catch {
+      ctx.warn('Auto-check skipped (run manually: sentix doctor)');
+    }
+
     if (!hasSafety) {
-      ctx.log('  2. Run: sentix safety set <안전어>');
-      ctx.log('  3. Run: sentix doctor');
-    } else {
-      ctx.log('  2. Run: sentix doctor');
+      ctx.log('');
+      ctx.log('Optional: sentix safety set <안전어>  (LLM 인젝션 방지)');
     }
     ctx.log('');
   },
@@ -465,3 +494,62 @@ exit $?
 
   ctx.success('Installed git pre-commit hook (verification gates)');
 }
+
+// ── Governor 강제 지시문 (기존 CLAUDE.md에 주입) ─────────
+
+function generateGovernorDirective() {
+  return `
+---
+
+# Sentix Governor — 필수 준수 사항
+
+> **이 프로젝트는 Sentix 프레임워크로 관리된다.**
+> **아래 규칙은 어떤 역할(/frontend, /backend 등)에서든 반드시 따라야 한다.**
+> 상세 설계: FRAMEWORK.md, 세부 규칙: docs/
+
+## 코드 수정 전 필수 절차
+
+\`\`\`
+1. 코드 수정 요청을 받으면 → 반드시 Governor 파이프라인으로 진입
+2. 직접 코드를 수정하지 않는다 — 항상 아래 순서를 따른다:
+   → planner (티켓 생성) → dev (구현) → pr-review (검증) → security → roadmap
+3. 테스트 스냅샷 필수: 작업 전 npm test 또는 프로젝트 테스트 실행
+4. 티켓 없이 코드 수정 금지 — sentix ticket create 또는 sentix feature add 사용
+\`\`\`
+
+## 파괴 방지 하드 룰 6개
+
+1. 작업 전 테스트 스냅샷 필수
+2. 티켓 SCOPE 밖 파일 수정 금지
+3. 기존 export/API 삭제 금지
+4. 기존 테스트 삭제/약화 금지
+5. 순삭제 50줄 제한
+6. 기존 기능/핸들러 삭제 금지
+
+> 상세: .sentix/rules/hard-rules.md
+> 에이전트 범위: docs/agent-scopes.md
+> Severity 분기: docs/severity.md
+
+## 작업 완료 체크리스트
+
+\`\`\`
+□ 하드 룰 6개 위반 없음
+□ 검증 게이트 통과 (sentix run 시 자동 — scope, export, test, deletion)
+□ 테스트 통과
+□ 티켓 생성됨
+□ README.md 업데이트됨 (변경된 기능이 있다면)
+□ lessons.md 업데이트됨 (실패 패턴이 있었다면)
+\`\`\`
+
+## Sentix CLI
+
+\`\`\`bash
+sentix run "요청"              # Governor 파이프라인 실행
+sentix ticket create "설명"    # 버그 티켓 생성
+sentix feature add "설명"      # 기능 티켓 생성
+sentix status                  # 상태 확인
+sentix doctor                  # 설치 진단
+sentix update                  # 프레임워크 최신화
+\`\`\`
+`;
+}

package/src/lib/pipeline.js

@@ -14,6 +14,8 @@
  */
 
 import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { runGates } from './verify-gates.js';
 
 /**
@@ -29,13 +31,20 @@ export async function runChainedPipeline(request, cycleId, state, ctx, options =
   const phases = [];
   const startTime = Date.now();
 
-  // lessons.md, patterns.md 로드 (있으면)
+  // lessons.md, patterns.md, agent-methods.md 로드 (있으면)
   const lessons = ctx.exists('tasks/lessons.md')
     ? await ctx.readFile('tasks/lessons.md')
     : '';
   const patterns = ctx.exists('tasks/patterns.md')
     ? await ctx.readFile('tasks/patterns.md')
     : '';
+  const agentMethods = ctx.exists('docs/agent-methods.md')
+    ? await ctx.readFile('docs/agent-methods.md')
+    : '';
+
+  const methodsDirective = agentMethods.trim()
+    ? `\n--- agent-methods.md (MANDATORY — follow method order strictly) ---\n${agentMethods}`
+    : '';
 
   const learningContext = [
     lessons.trim() ? `\n--- lessons.md ---\n${lessons.slice(0, 2000)}` : '',
@@ -56,6 +65,8 @@ export async function runChainedPipeline(request, cycleId, state, ctx, options =
     '3. List the specific files that need to be changed (SCOPE)',
     '4. Estimate complexity (low/medium/high)',
     '5. DO NOT write any code. ONLY plan.',
+    '6. Define WHAT and WHERE only. DO NOT specify HOW (implementation details, function names, algorithms, library choices).',
+    methodsDirective,
     learningContext,
   ].filter(Boolean).join('\n'), ctx);
 
@@ -78,11 +89,14 @@ export async function runChainedPipeline(request, cycleId, state, ctx, options =
     'You are the DEV agent. Your job:',
     latestTicket ? `Ticket:\n${latestTicket}` : `Request: "${request}"`,
     '',
-    '1. Implement the changes described in the ticket',
-    '2. Write or update tests',
-    '3. Run: npm test — ensure all tests pass',
-    '4. Self-verify: check hard rules (no export deletion, no test deletion, scope compliance, <50 net deletions)',
-    '5. DO NOT update version, README, or CHANGELOG — that is the FINALIZE phase',
+    '1. Follow dev methods: snapshot() → implement() → test() → verify() → report()',
+    '2. Implement the changes described in the ticket — you decide HOW',
+    '3. Write or update tests',
+    '4. Run: npm test — ensure all tests pass',
+    '5. Self-verify: hard rules ONLY (no export deletion, no test deletion, scope compliance, <50 net deletions)',
+    '6. DO NOT judge code quality — that is pr-review\'s job',
+    '7. DO NOT update version, README, or CHANGELOG — that is the FINALIZE phase',
+    methodsDirective,
     learningContext,
   ].filter(Boolean).join('\n'), ctx);
 
@@ -135,12 +149,18 @@ export async function runChainedPipeline(request, cycleId, state, ctx, options =
     `Test results: ${testResult.status === 0 ? 'ALL PASSED' : 'SOME FAILED — fix them'}`,
     `Verification gates: ${midGateInfo}`,
     '',
-    '1. Review the git diff (run: git diff)',
-    '2. If tests failed, fix the failing tests (fix code, not tests)',
-    '3. If gate violations exist, fix them',
-    '4. Ensure code quality and hard rule compliance',
-    '5. Run: npm test — confirm all pass after fixes',
-  ].join('\n'), ctx);
+    '1. Follow pr-review methods: diff() → validate() → grade() → calibrate() → verdict()',
+    '2. Review the git diff (run: git diff)',
+    '3. Validate hard rules first — any violation = immediate REJECTED',
+    '4. Grade on 4 criteria: Correctness, Consistency, Simplicity, Test Coverage',
+    '   (skip grade() for low complexity — hard rule pass is sufficient)',
+    '5. Calibrate: check tasks/lessons.md for past missed issues — be skeptical, not generous',
+    '6. If tests failed, fix the failing tests (fix code, not tests)',
+    '7. If gate violations exist, fix them',
+    '8. Run: npm test — confirm all pass after fixes',
+    methodsDirective,
+    learningContext,
+  ].filter(Boolean).join('\n'), ctx);
 
   phases.push({ name: 'review', ...reviewResult });
 
@@ -173,27 +193,59 @@ export async function runChainedPipeline(request, cycleId, state, ctx, options =
   };
 }
 
+// ── 에이전트 이름 → phase 이름 매핑 ────────────────────
+
+const AGENT_MAP = {
+  plan: 'planner',
+  dev: 'dev',
+  review: 'pr-review',
+  finalize: null,  // finalize는 전용 에이전트 없음
+};
+
 // ── Phase 실행 ────────────────────────────────────────
 
 function runPhase(name, prompt, ctx) {
-  const result = spawnSync('claude', ['-p', prompt], {
+  const args = ['-p', prompt, '--output-format', 'json'];
+
+  // .claude/agents/ 에 에이전트가 있으면 --agent 플래그 추가
+  const agentName = AGENT_MAP[name];
+  if (agentName && existsSync(join(ctx.cwd, '.claude', 'agents', `${agentName}.md`))) {
+    args.push('--agent', agentName);
+  }
+
+  const result = spawnSync('claude', args, {
     cwd: ctx.cwd,
-    stdio: 'inherit',
-    timeout: 300_000, // 5분 per phase (전체 10분 대신)
+    encoding: 'utf-8',
+    stdio: 'pipe',
+    timeout: 300_000, // 5분 per phase
   });
 
   if (result.error) {
     ctx.error(`Phase ${name} failed: ${result.error.message}`);
-    return { success: false, error: result.error.message, exit_code: null };
+    return { success: false, error: result.error.message, exit_code: null, output: null };
   }
 
   if (result.status !== 0) {
     ctx.error(`Phase ${name} exited with code ${result.status}`);
-    return { success: false, error: `exit code ${result.status}`, exit_code: result.status };
+    // stderr가 있으면 출력
+    if (result.stderr?.trim()) {
+      ctx.log(result.stderr.slice(-500));
+    }
+    return { success: false, error: `exit code ${result.status}`, exit_code: result.status, output: null };
+  }
+
+  // JSON 출력 파싱
+  let output = null;
+  try {
+    output = JSON.parse(result.stdout);
+    ctx.success(`Phase ${name} completed (${output.usage?.output_tokens || '?'} tokens)`);
+  } catch {
+    // JSON 파싱 실패 — 텍스트 그대로 사용
+    output = { content: result.stdout };
+    ctx.success(`Phase ${name} completed`);
   }
 
-  ctx.success(`Phase ${name} completed`);
-  return { success: true, error: null, exit_code: 0 };
+  return { success: true, error: null, exit_code: 0, output };
 }
 
 // ── 최근 티켓 내용 가져오기 ───────────────────────────