claude-memory-layer 1.0.11 → 1.0.12

package/memory/specs/task-entity-system/2026-02-25.md

@@ -0,0 +1,924 @@
+
+## 2026-02-25T12:31:26.421Z | a9796b08-6c4a-480f-8c45-e0faae66a868
+- type: session_summary
+- session: import:organized
+# Task Entity System Context
+
+> **Version**: 1.0.0
+> **Created**: 2026-01-31
+
+## 1. 배경
+
+### 1.1 기존 설계의 한계
+
+현재 code-memory 시스템에서 Task는 `entries` 테이블에 저장되는 불변 기록으로 관리됩니다:
+
+```typescript
+// 기존: entries 테이블에 Task를 저장
+{
+  entry_id: "ent_abc123",
+  entry_type: "task",
+  title: "벡터 검색 구현",
+  content_json: { status: "in_progress", ... }
+}
+```
+
+**문제점**:
+
+1. **세션 A**에서 "벡터 검색 구현" Task 생성 → `ent_abc123`
+2. **세션 B**에서 같은 Task 언급 → `ent_def456` (새 entry 생성!)
+3. **세션 C**에서 "완료" 언급 → `ent_ghi789` (또 새 entry!)
+
+결과: 하나의 Task가 3개의 분리된 entry로 존재하며, 상태 추적 불가
+
+### 1.2 해결 방향
+
+**Entry와 Entity 분리**:
+
+| 구분 | Entry | Entity |
+|------|-------|--------|
+| 특성 | 불변 기록 | 상태 변화 개체 |
+| 예시 | Fact, Decision, Insight | Task, Condition, Artifact |
+| 생명주기 | 생성 후 변경 없음 | 이벤트로 상태 변화 |
+| 식별 | UUID | canonical_key |
+
+## 2. Memo.txt 참고 사항
+
+### 2.1 핵심 원칙 (섹션 2)
+
+> **5. Task는 entity**
+> - Task 상태(status/priority/blockers)는 이벤트 fold 결과로 계산
+> - 세션마다 Task entry를 새로 만들지 말고, 기존 task entity를 찾아 업데이트
+
+### 2.2 DB 스키마 (섹션 4.3)
+
+```sql
+CREATE TABLE entities (
+  entity_id      VARCHAR PRIMARY KEY,
+  entity_type    VARCHAR NOT NULL,       -- task|condition|artifact
+  canonical_key  VARCHAR NOT NULL,
+  title          VARCHAR NOT NULL,
+  stage          VARCHAR NOT NULL,
+  status         VARCHAR NOT NULL,
+  current_json   JSON NOT NULL,
+  ...
+);
+```
+
+### 2.3 Task 이벤트 타입 (섹션 7.2)
+
+- `task_created`
+- `task_status_changed`
+- `task_priority_changed`
+- `task_blockers_set` (mode=replace|suggest)
+- `task_transition_rejected`
+
+### 2.4 BlockerResolver 규칙 (섹션 7.3)
+
+1. 강한 ID/URL/키 패턴 → artifact로 get-or-create
+2. 명시 task_id → task로 연결
+3. Task 제목 매칭 실패 → **condition으로 fallback** (스텁 Task 생성 금지)
+
+## 3. Idris2 영감 적용
+
+### 3.1 의존적 타입 개념
+
+**Idris2의 Vector 타입**:
+```idris
+-- 길이가 타입에 인코딩됨
+data Vect : Nat -> Type -> Type where
+  Nil  : Vect 0 a
+  (::) : a -> Vect n a -> Vect (S n) a
+```
+
+**TypeScript 적용**:
+```typescript
+// 상태에 따라 blockers 필드 타입이 달라짐
+type TaskState =
+  | { status: 'blocked'; blockers: BlockerRef[] }  // 필수, 1개 이상
+  | { status: 'done'; blockers?: never };          // 없어야 함
+```
+
+### 3.2 불변식 (Invariants)
+
+**Idris2에서**:
+```idris
+-- 타입 시스템이 강제
+nonEmptyBlockers : (t : Task) -> t.status = Blocked -> NonEmpty t.blockers
+```
+
+**TypeScript + Zod에서**:
+```typescript
+// 런타임 검증
+const BlockedTaskSchema = z.object({
+  status: z.literal('blocked'),
+  blockers: z.array(BlockerRefSchema).min(1)  // 최소 1개 강제
+});
+```
+
+### 3.3 왜 실제 Idris2를 사용하지 않는가?
+
+**Memo.txt 섹션 11**:
+> "지금은 Python 쪽 구현이 핵심이므로, Idris는 Candidate/Verified 래퍼 기반으로만 최소 수정"
+
+**실용적 이유**:
+
+1. **학습 곡선**: 팀원 모두가 Idris2를 학습해야 함
+2. **도구 체인**: idris2 컴파일러 설치/관리 필요
+3. **통합 복잡도**: TypeScript ↔ Idris2 FFI 오버헤드
+4. **디버깅**: 두 언어 간 스택 트레이스 추적 어려움
+
+**TypeScript로 충분한 이유**:
+
+1. **Discriminated Union**: 상태별 타입 분리 가능
+2. **Zod**: 런타임 검증으로 불변식 강제
+3. **타입 가드**: 조건부 타입 narrowing
+4. **생태계**: 풍부한 라이브러리와 도구
+
+## 4. 기존 코드와의 관계
+
+### 4.1 types.ts
+
+현재 정의된 타입 활용:
+
+```typescript
+// 기존
+export type MatchConfidence = 'high' | 'suggested' | 'none';
+export const MATCH_THRESHOLDS = {
+  minCombinedScore: 0.92,
+  minGap: 0.03,
+  suggestionThreshold: 0.75
+};
+
+// 확장
+export type EntityType = 'task' | 'condition' | 'artifact';
+export type TaskStatus = 'pending' | 'in_progress' | 'blocked' | 'done' | 'cancelled';
+```
+
+### 4.2 canonical-key.ts
+
+현재 함수 확장:
+
+```typescript
+// 기존: 이벤트용 canonical key
+export function makeCanonicalKey(title: string, context?: {...}): string;
+
+// 확장: 엔티티 타입별 canonical key
+export function makeEntityCanonicalKey(
+  entityType: EntityType,
+  identifier: string,
+  context?: { project?: string }
+): string {
+  switch (entityType) {
+    case 'task':
+      return `task:${context?.project ?? 'default'}:${normalize(identifier)}`;
+    case 'condition':
+      return `cond:${context?.project ?? 'default'}:${normalize(identifier)}`;
+    case 'artifact':
+      return makeArtifactKey(identifier);
+  }
+}
+```
+
+### 4.3 event-store.ts
+
+현재 EventStore 활용:
+
+```typescript
+// 기존 append 메서드 재활용
+// Task 이벤트도 동일하게 append-only로 저장
+const event = {
+  eventType: 'task_created',
+  sessionId,
+  content: JSON.stringify(payload),
+  ...
+};
+await eventStore.append(event);
+```
+
+### 4.4 matcher.ts
+
+현재 Matcher 로직 확장:
+
+```typescript
+// 기존: 이벤트 매칭
+export class Matcher {
+  matchSearchResults(results: SearchResult[]): MatchResult;
+}
+
+// 확장: Task 매칭에도 동일 로직 적용
+export class TaskMatcher {
+  // MATCH_THRESHOLDS 재활용
+  findSimilar(title: string, project: string): MatchResult;
+}
+```
+
+## 5. 경계 조건
+
+### 5.1 Unknown Blocker 처리
+
+```typescript
+// Task가 blocked인데 blockedBy가 비어있으면
+if (task.status === 'blocked' && blockedByTexts.length === 0) {
+  // 자동으로 placeholder condition 생성
+  const placeholder = await createCondition({
+    text: `Unknown blocker for ${task.title}`,
+    meta: { auto_placeholder: true }
+  });
+  blockers.push({ kind: 'condition', entity_id: placeholder.id });
+}
+```
+
+### 5.2 상태 전이 거부
+
+```typescript
+// pending → done 직접 전이 시
+if (from === 'pending' && to === 'done') {
+  // task_transition_rejected 이벤트 발행
+  await eventStore.append({
+    eventType: 'task_transition_rejected',
+    content: JSON.stringify({
+      task_id: task.id,
+      from_status: 'pending',
+      to_status: 'done',
+      reason: 'Direct transition from pending to done is not allowed'
+    })
+  });
+
+  // in_progress로 보정
+  return 'in_progress';
+}
+```
+
+### 5.3 Condition → Task 해결
+
+```typescript
+// 나중에 "API 키 설정됨" condition이 실제 Task로 식별되면
+await eventStore.append({
+  eventType: 'condition_resolved_to',
+  content: JSON.stringify({
+    condition_id: 'cond_xyz',
+    resolved_to: { kind: 'task', entity_id: 'task_abc' }
+  })
+});
+```
+
+## 6. 성능 고려사항
+
+### 6.1 캐싱
+
+```typescript
+// Entity 조회 캐시 (LRU)
+const entityCache = new LRUCache<string, Entity>({
+  max: 1000,
+  ttl: 1000 * 60 * 5  // 5분
+});
+```
+
+### 6.2 배치 처리
+
+```typescript
+// Projector는 배치로 이벤트 처리
+const BATCH_SIZE = 100;
+const events = await eventStore.fetchSince(offset, { limit: BATCH_SIZE });
+```
+
+### 6.3 인덱스 활용
+
+```sql
+-- FTS 검색용
+CREATE INDEX idx_entities_search ON entities USING GIN(to_tsvector('english', search_text));
+
+-- canonical_key 조회용
+CREATE INDEX idx_entities_type_key ON entities(entity_type, canonical_key);
+```
+
+## 7. 참고 자료
+
+- **Memo.txt**: AxiomMind Memory Graduation Pipeline 지시서
+- **spec.md**: `src/core/types.ts` - 기존 타입 정의
+- **AXIOMMIND 원칙**: Principle 5 - Task는 Entity
+- **Idris2 개념**: Dependent types, Linear types
+
+## 2026-02-25T12:31:26.428Z | fb683857-09e2-4b9c-b8c4-d6aa9b77f614
+- type: session_summary
+- session: import:organized
+# Task Entity System Implementation Plan
+
+> **Version**: 1.0.0
+> **Status**: Draft
+> **Created**: 2026-01-31
+
+## Phase 1: 기반 구조 (P0)
+
+### 1.1 타입 정의
+
+**파일**: `src/core/types.ts` 수정
+
+```typescript
+// 추가할 타입들
+export const EntityTypeSchema = z.enum(['task', 'condition', 'artifact']);
+export type EntityType = z.infer<typeof EntityTypeSchema>;
+
+export const TaskStatusSchema = z.enum(['pending', 'in_progress', 'blocked', 'done', 'cancelled']);
+export type TaskStatus = z.infer<typeof TaskStatusSchema>;
+
+export const TaskEventTypeSchema = z.enum([
+  'task_created',
+  'task_status_changed',
+  'task_priority_changed',
+  'task_blockers_set',
+  'task_transition_rejected'
+]);
+```
+
+**작업 항목**:
+- [ ] EntityType, TaskStatus 스키마 추가
+- [ ] TaskEvent 타입 정의
+- [ ] BlockerRef 타입 정의
+- [ ] TaskState Discriminated Union 정의
+
+### 1.2 DB 스키마 추가
+
+**파일**: `src/core/schema.sql` 수정
+
+**작업 항목**:
+- [ ] entities 테이블 생성
+- [ ] entity_aliases 테이블 생성
+- [ ] edges 테이블 생성
+- [ ] 인덱스 추가
+
+### 1.3 Canonical Key 확장
+
+**파일**: `src/core/canonical-key.ts` 수정
+
+```typescript
+// 추가할 함수
+export function makeEntityCanonicalKey(
+  entityType: EntityType,
+  identifier: string,
+  context?: { project?: string }
+): string;
+```
+
+**작업 항목**:
+- [ ] Task canonical key 함수
+- [ ] Condition canonical key 함수
+- [ ] Artifact canonical key 함수 (URL, JIRA, GitHub 패턴)
+
+## Phase 2: 핵심 컴포넌트 (P0)
+
+### 2.1 EntityRepository
+
+**파일**: `src/core/entity-repo.ts` (신규)
+
+```typescript
+export class EntityRepository {
+  constructor(private db: Database);
+
+  // CRUD (Create, Read만 - append-only 철학)
+  async create(entity: EntityInput): Promise<Entity>;
+  async findById(entityId: string): Promise<Entity | null>;
+  async findByCanonicalKey(type: EntityType, key: string): Promise<Entity | null>;
+
+  // 검색
+  async findSimilar(type: EntityType, searchText: string): Promise<Entity[]>;
+
+  // Alias 관리
+  async addAlias(entityId: string, alias: string): Promise<void>;
+  async resolveAlias(type: EntityType, alias: string): Promise<string | null>;
+
+  // 상태 업데이트 (이벤트 발행 후 projector가 호출)
+  async updateCurrentState(entityId: string, state: EntityState): Promise<void>;
+}
+```
+
+**작업 항목**:
+- [ ] EntityRepository 클래스 구현
+- [ ] findByCanonicalKey 구현
+- [ ] findSimilar 구현 (FTS 활용)
+- [ ] alias 관리 메서드 구현
+
+### 2.2 TaskMatcher
+
+**파일**: `src/core/task-matcher.ts` (신규)
+
+```typescript
+export class TaskMatcher {
+  constructor(
+    private entityRepo: EntityRepository,
+    private vectorStore: VectorStore
+  );
+
+  async findExact(canonicalKey: string): Promise<Task | null>;
+  async findSimilar(title: string, project: string): Promise<MatchResult>;
+  async suggestCandidates(title: string, project: string, limit?: number): Promise<Task[]>;
+}
+```
+
+**작업 항목**:
+- [ ] 정확 매칭 (entity_aliases 활용)
+- [ ] FTS 기반 유사 매칭
+- [ ] Vector 기반 semantic 매칭
+- [ ] 점수 계산 (stage weight, status weight, recency)
+- [ ] strict 확정 로직 (score >= 0.92, gap >= 0.03)
+
+### 2.3 BlockerResolver
+
+**파일**: `src/core/blocker-resolver.ts` (신규)
+
+**작업 항목**:
+- [ ] URL/JIRA/GitHub 패턴 감지
+- [ ] Artifact get-or-create 로직
+- [ ] Task 제목 매칭 시도
+- [ ] Condition fallback 생성
+- [ ] candidates 저장 로직
+
+### 2.4 TaskResolver
+
+**파일**: `src/core/task-resolver.ts` (신규)
+
+**작업 항목**:
+- [ ] Task entry 처리 로직
+- [ ] 기존 Task 찾기 (TaskMatcher 활용)
+- [ ] 이벤트 발행 로직
+- [ ] 상태 전이 검증
+- [ ] blockers 정규화 (BlockerResolver 활용)
+
+## Phase 3: Projection (P0)
+
+### 3.1 TaskProjector
+
+**파일**: `src/core/task-projector.ts` (신규)
+
+```typescript
+export class TaskProjector {
+  constructor(
+    private eventStore: EventStore,
+    private entityRepo: EntityRepository,
+    private edgeRepo: EdgeRepository
+  );
+
+  async projectIncremental(): Promise<ProjectionResult>;
+  async rebuild(): Promise<void>;
+
+  private async handleTaskCreated(event: TaskEvent): Promise<void>;
+  private async handleStatusChanged(event: TaskEvent): Promise<void>;
+  private async handleBlockersSet(event: TaskEvent): Promise<void>;
+}
+```
+
+**작업 항목**:
+- [ ] projection_offsets 관리
+- [ ] 증분 이벤트 읽기
+- [ ] 이벤트 타입별 핸들러
+- [ ] mode=replace 처리 (기존 edge 삭제 + 새 edge 삽입)
+- [ ] mode=suggest 처리 (suggested edge만)
+- [ ] current_json 갱신
+
+### 3.2 EdgeRepository
+
+**파일**: `src/core/edge-repo.ts` (신규)
+
+```typescript
+export class EdgeRepository {
+  async createEdge(edge: EdgeInput): Promise<Edge>;
+  async findEdges(srcId: string, relType?: string): Promise<Edge[]>;
+  async deleteEdges(srcId: string, relType: string): Promise<number>;
+  async replaceEdges(srcId: string, relType: string, newEdges: EdgeInput[]): Promise<void>;
+}
+```
+
+**작업 항목**:
+- [ ] Edge CRUD 구현
+- [ ] 관계 타입별 조회
+- [ ] replace 로직 (트랜잭션)
+
+## Phase 4: 통합 (P0)
+
+### 4.1 Graduation Pipeline 연동
+
+**파일**: `src/core/graduation.ts` 수정
+
+**작업 항목**:
+- [ ] Task entry 처리 시 TaskResolver 호출
+- [ ] 이벤트 발행 후 TaskProjector 호출
+- [ ] evidence edge 생성 로직
+
+### 4.2 EventStore 확장
+
+**파일**: `src/core/event-store.ts` 수정
+
+**작업 항목**:
+- [ ] Task 이벤트 타입 지원
+- [ ] fetch_since 메서드 추가 (projector용)
+- [ ] replay 메서드 추가 (rebuild용)
+
+## Phase 5: CLI 및 조회 (P1)
+
+### 5.1 조회 API
+
+**작업 항목**:
+- [ ] list_blocked_tasks()
+- [ ] list_tasks_with_only_suggested_blockers()
+- [ ] get_task_detail(task_id)
+- [ ] v_task_blockers_effective 뷰
+
+### 5.2 CLI 커맨드
+
+**파일**: `src/cli/index.ts` 수정
+
+**작업 항목**:
+- [ ] `cli blocked` - blocked task 목록
+- [ ] `cli task show <task_id>` - task 상세
+- [ ] `cli tasks --status <status>` - 상태별 목록
+
+## 파일 목록
+
+### 신규 파일
+```
+src/core/entity-repo.ts
+src/core/edge-repo.ts
+src/core/task-matcher.ts
+src/core/blocker-resolver.ts
+src/core/task-resolver.ts
+src/core/task-projector.ts
+```
+
+### 수정 파일
+```
+src/core/types.ts
+src/core/canonical-key.ts
+src/core/event-store.ts
+src/core/graduation.ts
+src/cli/index.ts
+```
+
+## 테스트
+
+### 필수 테스트 케이스
+
+1. **Task 동일성**
+   - 같은 제목의 Task가 여러 세션에서 언급되어도 하나의 Entity로 관리
+
+2. **상태 전이**
+   - pending → done 직접 전이 시 에러
+   - blocked 상태에서 blockers가 비어있으면 에러
+
+3. **Idempotency**
+   - 동일 세션 재처리 시 중복 이벤트 없음
+   - 동일 edge 중복 생성 없음
+
+4. **Blocker 해결**
+   - URL → Artifact 정상 생성
+   - Task 제목 매칭 실패 → Condition 생성 + candidates 저장
+
+## 의존성 그래프
+
+```
+types.ts
+    │
+    ├── entity-repo.ts
+    │       │
+    │       ├── task-matcher.ts
+    │       │
+    │       └── edge-repo.ts
+    │               │
+    │               └── task-projector.ts
+    │
+    ├── blocker-resolver.ts ─────────┐
+    │                                │
+    └── task-resolver.ts ◀───────────┘
+            │
+            └── graduation.ts
+```
+
+## 마일스톤
+
+| 단계 | 완료 기준 |
+|------|----------|
+| M1 | 타입 정의 + DB 스키마 |
+| M2 | EntityRepo + EdgeRepo 동작 |
+| M3 | TaskMatcher 동작 (정확 매칭만) |
+| M4 | BlockerResolver + TaskResolver 동작 |
+| M5 | TaskProjector 동작 (증분 처리) |
+| M6 | Graduation 연동 완료 |
+| M7 | CLI 조회 커맨드 완료 |
+
+## 2026-02-25T12:31:26.435Z | fc140be7-1e67-4a23-822b-e83e23b295c0
+- type: session_summary
+- session: import:organized
+# Task Entity System Specification
+
+> **Version**: 1.0.0
+> **Status**: Draft
+> **Created**: 2026-01-31
+
+## 1. 개요
+
+### 1.1 문제 정의
+
+현재 시스템에서 Task는 세션별로 entry(기록)로 저장되어 다음 문제가 발생:
+
+1. **중복 생성**: 같은 Task가 여러 세션에서 언급될 때마다 새 entry 생성
+2. **상태 단절**: Task 상태 변경 이력이 세션 단위로 분리되어 추적 불가
+3. **관계 손실**: Task 간 blockedBy 관계가 세션 경계에서 단절
+
+### 1.2 해결 방향
+
+**Task를 Entity로 승격**:
+- Task는 고유한 Entity로 관리 (entries와 분리된 entities 테이블)
+- 상태 변경은 이벤트로 기록 (event-sourced)
+- fold 연산으로 현재 상태 계산
+
+## 2. 핵심 개념
+
+### 2.1 Entity vs Entry
+
+| 구분 | Entry (기존) | Entity (신규) |
+|------|-------------|--------------|
+| 정의 | 세션에서 추출된 불변 기록 | 시간에 따라 상태가 변화하는 개체 |
+| 예시 | Fact, Decision, Insight | Task, Condition, Artifact |
+| 식별 | entry_id (UUID) | entity_id + canonical_key |
+| 상태 | 불변 (created once) | 이벤트 fold로 계산 |
+
+### 2.2 Canonical Key
+
+Entity의 동일성을 판단하는 정규화된 키:
+
+```typescript
+// Task
+task:{project}:{normalize(title)}
+// 예: task:code-memory:implement-vector-search
+
+// Condition
+cond:{project}:{normalize(text)}
+// 예: cond:code-memory:api-key-configured
+
+// Artifact
+art:url:{sha1(url)}           // URL
+art:jira:{key}                // JIRA
+art:gh_issue:{repo}:{num}     // GitHub Issue
+```
+
+### 2.3 Task 상태 머신
+
+```
+         ┌─────────────────────────────────────┐
+         │                                     │
+         ▼                                     │
+    ┌─────────┐     ┌───────────┐     ┌────────┴───┐
+    │ pending │────▶│in_progress│────▶│   done     │
+    └────┬────┘     └─────┬─────┘     └────────────┘
+         │                │
+         │                ▼
+         │          ┌──────────┐
+         └─────────▶│ blocked  │
+                    └──────────┘
+                         │
+                         │ (blockers 해결 시)
+                         ▼
+                    ┌──────────┐
+                    │in_progress│
+                    └──────────┘
+```
+
+**불변식 (Invariants)**:
+- `blocked` 상태면 `blockers[]` 비어있으면 안 됨
+- `done` 상태면 `blockers[]` 비어있어야 함
+- `pending` → `done` 직접 전이 금지 (in_progress 거쳐야 함)
+
+## 3. 이벤트 타입
+
+### 3.1 Task 이벤트
+
+```typescript
+type TaskEventType =
+  | 'task_created'           // 신규 생성
+  | 'task_status_changed'    // 상태 변경
+  | 'task_priority_changed'  // 우선순위 변경
+  | 'task_blockers_set'      // blockers 설정/변경
+  | 'task_transition_rejected'; // 전이 거부 (디버깅용)
+```
+
+### 3.2 이벤트 페이로드 스키마
+
+```typescript
+// task_created
+interface TaskCreatedPayload {
+  task_id: string;
+  canonical_key: string;
+  title: string;
+  initial_status: 'pending' | 'in_progress'; // done 금지
+  priority?: 'low' | 'medium' | 'high' | 'critical';
+  source_entry_id: string;
+}
+
+// task_status_changed
+interface TaskStatusChangedPayload {
+  task_id: string;
+  from_status: TaskStatus;
+  to_status: TaskStatus;
+  reason?: string;
+}
+
+// task_blockers_set
+interface TaskBlockersSetPayload {
+  task_id: string;
+  mode: 'replace' | 'suggest';
+  blockers: BlockerRef[];
+  source_entry_id?: string;
+}
+```
+
+## 4. 컴포넌트 설계
+
+### 4.1 TaskMatcher
+
+기존 Task 찾기:
+
+```typescript
+interface TaskMatcher {
+  // 정확한 매칭
+  findExact(canonicalKey: string): Task | null;
+
+  // 유사도 기반 매칭
+  findSimilar(title: string, project: string): MatchResult;
+
+  // 후보 목록 반환
+  suggestCandidates(title: string, project: string, limit?: number): Task[];
+}
+
+// 매칭 조건 (strict 확정)
+const STRICT_MATCH = {
+  minScore: 0.92,
+  minGap: 0.03,  // top1 - top2
+  status: ['active'],  // cancelled 제외
+  taskStatus: ['pending', 'in_progress', 'blocked']  // done 제외
+};
+```
+
+### 4.2 BlockerResolver
+
+blockedBy 텍스트를 Entity 참조로 변환:
+
+```typescript
+interface BlockerRef {
+  kind: 'task' | 'condition' | 'artifact';
+  entity_id: string;
+  raw_text: string;
+  confidence: 'high' | 'suggested' | 'none';
+  candidates?: EntityRef[];  // confidence='none'일 때
+}
+
+interface BlockerResolver {
+  resolve(
+    blockedByTexts: string[],
+    project: string,
+    sourceEntryId: string
+  ): Promise<BlockerRef[]>;
+}
+```
+
+**해결 규칙**:
+1. 강한 패턴 (URL, JIRA key) → Artifact로 get-or-create
+2. 명시 task_id → Task 연결 (없으면 Condition으로 fallback)
+3. Task 제목 매칭 실패 → Condition으로 생성 + candidates 저장
+4. **스텁 Task 생성 금지** (중복 지옥 방지)
+
+### 4.3 TaskResolver
+
+세션에서 추출된 Task entry 처리:
+
+```typescript
+interface TaskResolver {
+  processTaskEntry(entry: TaskEntry): Promise<{
+    task_id: string;
+    events: TaskEvent[];
+    isNew: boolean;
+  }>;
+}
+```
+
+**처리 흐름**:
+1. canonical_key로 기존 Task 찾기
+2. 없으면 `task_created` 이벤트 발행
+3. priority/status 변경 필요 시 이벤트 발행
+4. blockers가 있으면 BlockerResolver로 정규화
+5. evidenceAligned → `mode=replace`, 아니면 `mode=suggest`
+6. `task_blockers_set` 이벤트 발행
+
+### 4.4 TaskProjector
+
+이벤트를 entities/edges에 반영:
+
+```typescript
+interface TaskProjector {
+  // 증분 처리
+  projectIncremental(): Promise<ProjectionResult>;
+
+  // 전체 rebuild
+  rebuild(): Promise<void>;
+}
+```
+
+**mode=replace**:
+- 기존 blocked_by edges 삭제
+- 새 edges 삽입
+- entities.current_json.blockers 갱신
+
+**mode=suggest**:
+- blocked_by_suggested edges만 insert/replace
+- entities.current_json.blocker_suggestions 누적
+
+## 5. DB 스키마
+
+### 5.1 entities 테이블
+
+```sql
+CREATE TABLE entities (
+  entity_id      VARCHAR PRIMARY KEY,
+  entity_type    VARCHAR NOT NULL,       -- task|condition|artifact
+  canonical_key  VARCHAR NOT NULL,
+  title          VARCHAR NOT NULL,
+  stage          VARCHAR NOT NULL,       -- raw|working|candidate|verified|certified
+  status         VARCHAR NOT NULL,       -- active|contested|deprecated|superseded
+  current_json   JSON NOT NULL,          -- fold된 현재 상태
+  title_norm     VARCHAR,                -- 정규화된 제목 (검색용)
+  search_text    VARCHAR,                -- FTS용 텍스트
+  created_at     TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at     TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX idx_entities_type_key ON entities(entity_type, canonical_key);
+CREATE INDEX idx_entities_status ON entities(status);
+```
+
+### 5.2 entity_aliases 테이블
+
+동일 Entity의 여러 이름:
+
+```sql
+CREATE TABLE entity_aliases (
+  entity_type   VARCHAR NOT NULL,
+  canonical_key VARCHAR NOT NULL,
+  entity_id     VARCHAR NOT NULL,
+  is_primary    BOOLEAN DEFAULT FALSE,
+  created_at    TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY(entity_type, canonical_key)
+);
+```
+
+## 6. Idris2 영감 적용
+
+### 6.1 타입 레벨 보장 (TypeScript)
+
+```typescript
+// Discriminated Union으로 상태별 타입 분리
+type TaskState =
+  | { status: 'pending'; blockers?: never }
+  | { status: 'in_progress'; blockers?: never }
+  | { status: 'blocked'; blockers: BlockerRef[] }  // 비어있으면 안 됨
+  | { status: 'done'; blockers?: never };
+
+// 타입 가드
+function isBlocked(task: TaskState): task is { status: 'blocked'; blockers: BlockerRef[] } {
+  return task.status === 'blocked' && task.blockers.length > 0;
+}
+```
+
+### 6.2 불변식 검증
+
+```typescript
+// Zod 스키마로 런타임 검증
+const TaskInvariantSchema = z.discriminatedUnion('status', [
+  z.object({
+    status: z.literal('blocked'),
+    blockers: z.array(BlockerRefSchema).min(1)  // 최소 1개
+  }),
+  z.object({
+    status: z.literal('done'),
+    blockers: z.array(BlockerRefSchema).max(0)  // 0개
+  }),
+  // ...
+]);
+```
+
+### 6.3 왜 실제 Idris2를 사용하지 않는가?
+
+**Memo.txt 지침** (섹션 11):
+> "지금은 Python 쪽 구현이 핵심이므로, Idris는 Candidate/Verified 래퍼 기반으로만 최소 수정"
+
+**실용적 이유**:
+1. 팀 학습 곡선 최소화
+2. 도구 체인 단순화 (idris2 설치/관리 불필요)
+3. TypeScript + Zod로 충분한 타입 안전성 확보
+4. 런타임 검증이 실제 버그 방지에 더 효과적
+
+## 7. 성공 기준
+
+- [ ] Task가 세션 간 동일성 유지 (canonical_key 기반)
+- [ ] 상태 변경 이력이 이벤트로 추적 가능
+- [ ] blockers가 Entity 참조로 정규화됨
+- [ ] 불변식 위반 시 에러 발생 (blocked인데 blockers 비어있음 등)
+- [ ] 기존 entry 시스템과 호환 유지