planning-contract/SPEC.md

@@ -0,0 +1,171 @@
+# 계획 계약 명세서 (Planning Contract Specification)
+
+## 개요
+
+MiniMax 기반 에이전트의 계획 계약은 에이전트가 수립한 계획의 품질, 완전성, 실행 가능성을 보장하기 위한 명세서이다. 본 문서는 계약의 각 조항과 그에 대한 검증 기준을 정의한다.
+
+---
+
+## 용어 정의
+
+| 용어 | 정의 |
+|------|------|
+| **계약 (Contract)** | 에이전트의 계획 수립 행위에 대한 명시적 약속 및 조건 |
+| **조항 (Clause)** | 계약의 구성 단위로서 특정 요구사항을 표현 |
+| **검증 기준 (Verification Criteria)** | 조항의 성립 여부를 판단하는 성공/실패 조건 |
+| **계획 (Plan)** | 목표 달성을 위한 단계별 행동 시퀀스 |
+| **에피타이드 (Epitaph)** | 계획 실행 결과의 기록 및 평가 |
+
+---
+
+## 계약 조항 명세
+
+### 조항 1: 목표 명확성 (Goal Clarity)
+
+**설명**: 수립된 계획은 명확하고 측정 가능한 목표를 포함해야 한다.
+
+**검증 기준**:
+
+| 구분 | 조건 |
+|------|------|
+| **성공 조건** | - 목표가 구체적인 수치 또는 상태로 표현됨<br>- 목표 달성을 판단할 수 있는 명확한 기준 존재<br>- 목표가 단일 책임 원칙을 따름 (하나의 주요 결과) |
+| **실패 조건** | - 목표가 모호한 표현으로 기술됨 (예: "좋게 만들기")<br>- 성공/실패 판단 기준이 없음<br>- 하나의 계획에 두 개 이상의 독립적 목표 포함 |
+
+---
+
+### 조항 2: 단계 완전성 (Step Completeness)
+
+**설명**: 계획은 목표 달성까지 필요한 모든 단계를 포함해야 한다.
+
+**검증 기준**:
+
+| 구분 | 조건 |
+|------|------|
+| **성공 조건** | - 각 단계가 선행 조건을 만족함<br>- 모든 의존성 단계가 순서대로 배치됨<br>- 최종 단계에서 목표 달성 보장 |
+| **실패 조건** | - 필수 단계가 누락됨<br>- 단계 간 의존성 순서 위반<br>- 목표에 도달하지 않는 불완전한 시퀀스 |
+
+---
+
+### 조항 3: 실행 가능성 (Executability)
+
+**설명**: 계획의 각 단계는 현재 환경에서 실행 가능한 명령이어야 한다.
+
+**검증 기준**:
+
+| 구분 | 조건 |
+|------|------|
+| **성공 조건** | - 각 단계의 명령어가 시스템에서 사용 가능함<br>- 필요한 리소스(파일, 권한, 도구)가 확보됨<br>- 단계 실행에 대한 타임아웃이 설정됨 |
+| **실패 조건** | - 존재하지 않는 명령어 또는 도구 참조<br>- 필요한 리소스 접근 권한 없음<br>- 무한 대기 가능성이 있는 단계 포함 |
+
+---
+
+### 조항 4: 리스크 평가 (Risk Assessment)
+
+**설명**: 계획은 잠재적 리스크를 식별하고 완화 전략을 포함해야 한다.
+
+**검증 기준**:
+
+| 구분 | 조건 |
+|------|------|
+| **성공 조건** | - 각 단계별 잠재적 리스크 명시됨<br>- 리스크 발생 시 대안 경로 또는 복구 전략 존재<br>- 중요 리스크에 대한 회피 또는 감소 조치 포함 |
+| **실패 조건** | - 리스크 식별 없이 진행<br>- 복구 전략 없는 단일 실패 지점 존재<br>- 치명적 리스크에 대한 무시 |
+
+---
+
+### 조항 5: 검증 가능성 (Verifiability)
+
+**설명**: 계획의 각 단계는 실행 후 결과를 검증할 수 있어야 한다.
+
+**검증 기준**:
+
+| 구분 | 조건 |
+|------|------|
+| **성공 조건** | - 각 단계에 대한 예상 결과 명시됨<br>- 성공/실패를 판단하는 어설션 존재<br>- 검증 방법이 자동화 가능함 |
+| **실패 조건** | - 단계 실행 결과 확인 방법 없음<br>- 주관적 판단에만 의존하는 검증<br>- 검증 불가능한 상태 변경 포함 |
+
+---
+
+### 조항 6: 시간적 제약 (Temporal Constraints)
+
+**설명**: 계획은 실행 시간에 대한 합리적인 제약 조건을 포함해야 한다.
+
+**검증 기준**:
+
+| 구분 | 조건 |
+|------|------|
+| **성공 조건** | - 전체 계획에 대한 예상 소요 시간 명시<br>- 각 단계별 타임아웃 설정<br>- 시간 초과 시 대체 전략 존재 |
+| **실패 조건** | - 시간 제약 없이 무한 대기 가능<br>- 현실적이지 않은 시간 추정<br>- 타임아웃 없는 장시간 작업 |
+
+---
+
+### 조항 7: 롤백 가능성 (Rollback Capability)
+
+**설명**: 계획은 실패 시 이전 상태로 복구할 수 있는 메커니즘을 포함해야 한다.
+
+**검증 기준**:
+
+| 구분 | 조건 |
+|------|------|
+| **성공 조건** | - 각 변경 단계에 대한 롤백 명령 정의됨<br>- 롤백 실행 순서가 명확함<br>- 롤백 성공 여부 검증 방법 존재 |
+| **실패 조건** | - 롤백 메커니즘 없음<br>- 일관성 없는 롤백 시퀀스<br>- 롤백 불가능한 영구 변경 포함 |
+
+---
+
+## 계약 등급
+
+| 등급 | 충족 조항 수 | 설명 |
+|------|-------------|------|
+| **A (최상)** | 7/7 | 모든 조항 충족, 최고 품질 보장 |
+| **B (양호)** | 5-6/7 | 주요 조항 충족, 일부 개선 필요 |
+| **C (미흡)** | 3-4/7 | 기본 구조는 있으나 신뢰성 낮음 |
+| **D (위험)** | 1-2/7 | 심각한 결함, 실행 권장 불가 |
+| **F (실패)** | 0/7 | 계약 미충족, 계획 부적격 |
+
+---
+
+## 검증 프로세스
+
+```
+┌─────────────┐    ┌──────────────┐    ┌─────────────┐
+│  계획 수립   │───▶│ 계약 검증    │───▶│ 등급 부여   │
+└─────────────┘    └──────────────┘    └─────────────┘
+                          │
+                          ▼
+                   ┌──────────────┐
+                   │ 실패 조항 분석 │
+                   └──────────────┘
+```
+
+---
+
+## 에피타이드 기록 스키마
+
+```json
+{
+  "planId": "string",
+  "timestamp": "ISO8601",
+  "grade": "A|B|C|D|F",
+  "clauses": {
+    "goalClarity": { "passed": boolean, "details": "string" },
+    "stepCompleteness": { "passed": boolean, "details": "string" },
+    "executability": { "passed": boolean, "details": "string" },
+    "riskAssessment": { "passed": boolean, "details": "string" },
+    "verifiability": { "passed": boolean, "details": "string" },
+    "temporalConstraints": { "passed": boolean, "details": "string" },
+    "rollbackCapability": { "passed": boolean, "details": "string" }
+  },
+  "executionResult": {
+    "status": "success|partial|failure",
+    "duration": "number (ms)",
+    "deviationFromPlan": "string|null"
+  }
+}
+```
+
+---
+
+## 변경 이력
+
+| 버전 | 날짜 | 변경 내용 |
+|------|------|----------|
+| 1.0.0 | 2026-07-14 | 초기 버전 작성 |