claude-memory-layer 1.0.0

package/specs/task-entity-system/plan.md

@@ -0,0 +1,301 @@
+# 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 조회 커맨드 완료 |

package/specs/task-entity-system/spec.md

@@ -0,0 +1,314 @@
+# 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 시스템과 호환 유지