autonomous-flow-daemon 1.0.0 → 1.6.0

package/CHANGELOG.md

@@ -7,6 +7,45 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [1.5.0] - 2026-04-02 — "Trust-Builder"
+
+> The immune system now speaks. Three pillars that make afd's defenses visible, self-improving, and smarter.
+
+### Added
+
+- **Hologram L1 — Import-Based Semantic Compression**
+  - New optional `contextFile` parameter on `afd_hologram` MCP tool and `/hologram` HTTP endpoint
+  - `extractImportedSymbols()` function: regex fast-path parsing of named imports, default imports, and namespace imports from the context file
+  - L1 filtering in `generateHologram()`: directly imported symbols receive full type signatures; non-imported exports are reduced to name-only stubs with guide text `// details omitted — read directly if needed`
+  - Namespace imports (`import * as X`) trigger full L0 hologram (safe default, no false filtering)
+  - Silent fallback to L0 when `contextFile` is missing, unreadable, or yields zero import results
+  - Compression target: 85%+ with contextFile (vs ~80% L0 baseline)
+  - L1 is MCP/HTTP path only — S.E.A.M hot path remains L0 to protect the 270ms budget
+
+- **Antibody Passive Defense — Mistake History Injection**
+  - New `mistake_history` SQLite table: `file_path`, `mistake_type`, `description` (max 200 chars), `antibody_id`, `timestamp`
+  - Indexes on `file_path` and `timestamp` for sub-millisecond query performance
+  - Write-through cache: `mistakeCache: Map<string, MistakeEntry[]>` loaded on daemon startup, updated on every insert
+  - Per-file cap of 5 most recent entries enforced at write time
+  - 30-day TTL purge on daemon startup (consistent with `telemetry` table pattern)
+  - Direct DB insert on auto-heal events (not via HTTP POST): records `mistake_type` from `symptom.patternType` and `description` from `symptom.title`
+  - New GET `/mistake-history?file=<path>` HTTP endpoint (returns max 5 entries, most recent first)
+  - `pastMistakes` field injected into `afd diagnose --format a2a` output on both the healthy path (proactive warning) and the auto-heal path (reactive)
+  - `pastMistakes` is omitted entirely when no history exists (zero token overhead)
+  - Path normalization: `file_path` stored with forward slashes (cross-platform safe)
+
+- **HUD Defense Counter + Reasons**
+  - `/mini-status` endpoint enhanced with `total_defenses: number` and `defense_reasons: string[]` (in-memory only, no DB query — always under 200ms)
+  - `defense_reasons` derived from in-memory `state.autoHealLog` (capped at 100 entries), returning up to 3 most recent unique `mistake_type` values
+  - Status bar format: `[afd] {N}건 방어 ({reason1}, {reason2}, ...)` when defenses exist; `[afd] ON` when none
+  - Existing `healed_count` and `last_healed` fields preserved for backward compatibility
+
+### Fixed
+
+- **Windows path normalization in `assertInsideWorkspace()`**: backslash (`\`) separators in Windows paths are now normalized to forward slashes before workspace boundary checks, fixing false-positive "outside workspace" errors on Windows
+
+---
+
 ## [1.0.0] - 2026-03-31 — "The Immortal Flow"
 
 > [afd] 🛡️ AI agent deleted '.claudeignore' | 🩹 Self-healed in 184ms | Context preserved.

package/README.ko.md

@@ -6,7 +6,16 @@
 <p align="center"><strong>AI가 스스로 고치는 개발 환경. 복구까지 단 0.2초.</strong></p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/version-1.0.0-blue?style=flat-square" alt="version" />
+  <a href="https://github.com/dotoricode/autonomous-flow-daemon">
+    <img src="demo.gif" width="850" alt="afd demo" style="border-radius: 12px; box-shadow: 0 20px 40px rgba(0,0,0,0.4);">
+  </a>
+</p>
+
+---
+
+<p align="center">
+  <img src="https://img.shields.io/badge/version-1.6.0-blue?style=flat-square" alt="version" />
+  <a href="https://www.npmjs.com/package/autonomous-flow-daemon"><img src="https://img.shields.io/npm/v/autonomous-flow-daemon?style=flat-square&logo=npm&color=cb0000" alt="npm" /></a>
   <img src="https://img.shields.io/badge/runtime-Bun-f472b6?style=flat-square&logo=bun" alt="Bun" />
   <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT" />
   <img src="https://img.shields.io/badge/built%20for-Claude%20Code-7c3aed?style=flat-square" alt="Claude Code" />
@@ -20,24 +29,75 @@
 
 ## 왜 afd인가?
 
-> [afd] 🛡️ AI가 '.claudeignore'를 삭제했습니다 | 🩹 184ms 만에 자가 복구 완료 | 컨텍스트 보존됨.
+> [afd] AI가 '.claudeignore'를 삭제했습니다 | 184ms 만에 자가 복구 완료 | 컨텍스트 보존됨.
 
-당신은 지금 몰입의 정점에 있습니다. AI 에이전트가 실수로 설정 파일을 삭제하거나, 훅 파일을 망가뜨립니다. `afd` 없이는 작업을 멈추고, 원인을 진단하고, 직접 고쳐야 합니다: **30분이 날아갑니다**.
+AI 에이전트가 실수로 설정 파일을 삭제하거나, 훅 파일을 망가뜨립니다. `afd` 없이는 작업을 멈추고, 원인을 진단하고, 직접 고쳐야 합니다: **30분이 날아갑니다**.
 
-`afd`가 있다면, 데몬이 10ms 만에 이상을 감지하고, 184ms 안에 복구를 완료합니다. **당신은 아무것도 몰랐습니다.**
+`afd`가 있다면, 데몬이 10ms 만에 이상을 감지하고, 184ms 안에 복구를 완료합니다. **당신은 아무것도 몰랐습니다.** Bun 기반 네이티브 데몬으로 CPU 0.1% 미만, 메모리 ~40MB만 사용합니다.
 
 | 상황 | afd 없을 때 | afd 있을 때 |
 |:-----|:------------|:------------|
 | AI가 `.claudeignore` 삭제 | 30분 수동 복구 | **0.2초 자동 치유** |
 | 훅 파일 손상 | 훅 재주입, 세션 재시작 | **백그라운드 자동 복구** |
 | `git checkout`으로 파일 50개 동시 변경 | AI가 폭주 | **대규모 이벤트 억제기 작동** |
-| 신규 팀원, 환경 설정 없음 | 구전으로 전달 | **`afd sync`로 즉시 백신 접종** |
+| AI가 대용량 파일 8개 읽기 (114KB) | ~28,600 토큰 소비 | **홀로그램으로 ~1,700 토큰 (94% 절감)** |
+
+---
+
+## 주요 기능
+
+| 기능 | 설명 |
+|:-----|:-----|
+| **S.E.A.M 자율 치유** | 파일 삭제/손상을 감지하고 270ms 이내에 복구 |
+| **홀로그램 추출** | MCP를 통해 80-93% 가벼운 타입 뼈대를 AI 에이전트에 제공, 토큰 비용 대폭 절감 |
+| **스마트 파일 리더** | `afd_read` — 작은 파일은 원본, 큰 파일은 자동 홀로그램 압축; 라인 범위 읽기 지원 |
+| **워크스페이스 맵** | `afd://workspace-map` — 전체 파일 트리 + export 시그니처를 한 번에 제공 |
+| **홀로그램 L1** | import 기반 정밀 압축 — 실제 import된 심볼만 전체 시그니처 유지 (85%+ 절감) |
+| **격리 구역** | 복구 전 손상된 파일을 `.afd/quarantine/`에 백업 |
+| **자가 진화** | 격리된 실패 사례를 분석하여 `afd-lessons.md`에 방지 규칙 자동 생성 |
+| **실수 이력 주입** | PreToolUse 훅이 파일 편집 전 과거 실수를 경고로 주입 |
+| **더블탭 감지** | 한 번 삭제 = 자동 복구; 30초 내 재삭제 = 사용자 의도로 존중 |
+| **백신 네트워크** | `afd sync`로 학습된 항체를 팀 전체에 전파 |
+| **MCP 통합** | `afd mcp install`로 MCP 서버 자동 등록 |
+| **HUD 방어 카운터** | 상태 표시줄에 방어 건수와 사유 요약을 한눈에 표시 |
 
 ---
 
-## 🚀 명령어 한 줄로 끝나는 경험
+## 토큰 절약 — 실측 데이터
+
+홀로그램 시스템은 AI 기반 개발에서 afd의 가장 큰 가치입니다. 실제 세션에서 측정한 결과입니다:
+
+### 세션 스냅샷 (실제 코딩 세션에서 측정)
+
+| 지표 | 값 |
+|:-----|:---|
+| 홀로그램 요청 횟수 | 8회 |
+| 대상 파일 총 크기 | ~114.5 KB (8개 파일, 평균 14.3 KB) |
+| 원본 토큰 비용 | ~28,600 토큰 |
+| 홀로그램 압축 후 | ~1,700 토큰 |
+| **절약된 토큰** | **~26,900 토큰 (94% 절감)** |
+
+### 규모별 효과
 
-> **"더 이상의 설정 삽질은 없습니다. 완전한 방어 환경을 구축하세요."**
+```
+세션 사용 토큰 (ctx ~15%):  ~150,000  ████████████████
+홀로그램 절약 토큰:          ~26,900  ██░░░░░░░░░░░░░░  (세션의 18%)
+```
+
+ctx 50% 이상에서는 파일 읽기가 토큰 예산의 대부분을 차지합니다. 홀로그램 없이 대용량 파일 8개를 읽으면 매번 ~28.6K 토큰이 소비됩니다. 홀로그램을 사용하면 **각 파일을 원본의 1/16 비용**으로 읽을 수 있으며, 반복 읽기가 많을수록 격차는 더 벌어집니다.
+
+### 토큰 최적화 3단계
+
+| 레이어 | 도구 | 절감률 | 방식 |
+|:-------|:-----|:-------|:-----|
+| **L0 홀로그램** | `afd_hologram` | 80%+ | 함수 본문 제거, 타입 시그니처만 보존 |
+| **L1 홀로그램** | `afd_hologram` + `contextFile` | 85%+ | import된 심볼만 필터링 |
+| **스마트 리더** | `afd_read` | 자동 | 10KB 미만은 원본, 이상은 자동 홀로그램 |
+| **워크스페이스 맵** | `afd://workspace-map` | N/A | 프로젝트 전체 구조를 한 번에 파악 |
+
+---
+
+## 명령어 한 줄로 시작
 
 ```bash
 npx @dotoricode/afd start
@@ -51,25 +111,22 @@ bun link && afd start
 
 이게 전부입니다. 나머지는 `afd`가 알아서 처리합니다:
 
-- **자동 훅(Hook) 주입** — Claude Code의 `PreToolUse` 훅을 자동으로 설치합니다. 더 이상 `.json` 파일을 직접 수정하며 고생하지 마세요.
-- **초고속 실시간 감시** — `.claude/`, `CLAUDE.md`, `.cursorrules` 등 핵심 파일을 10ms 단위로 모니터링합니다.
-- **배경 자율 치유** — 파일이 삭제되거나 손상되면 **S.E.A.M 사이클**이 조용히 복구합니다. 사용자가 눈치채기도 전에 모든 상황은 종료됩니다.
+- **자동 훅 주입** — Claude Code의 `PreToolUse` 훅을 자동으로 설치합니다.
+- **초고속 실시간 감시** — 핵심 설정 파일을 10ms 단위로 모니터링합니다.
+- **배경 자율 치유** — S.E.A.M 사이클이 조용히 복구합니다.
 
 ```
 $ afd start
-  🛡️ afd 데몬 시작 (pid 4812, port 52413)
-  ✅ .claude/hooks.json에 감시 훅 주입 완료
-  👀 감시 중: .claude/, CLAUDE.md, .cursorrules
-  ✨ 준비되었습니다.
+  데몬 시작 (pid 4812, port 52413)
+  스마트 탐색: AI 컨텍스트 대상 7개 감시 시작
+  .claude/hooks.json에 감시 훅 주입 완료
 ```
 
-> `afd start`를 치고 나면 그냥 잊어버리세요. 그것이 우리가 추구하는 최고의 UX입니다.
-
 ---
 
-## 🧠 지능형 치유 엔진: S.E.A.M 사이클
+## S.E.A.M 사이클
 
-`afd`의 핵심 로직입니다. 모든 파일 변화는 다음의 4단계를 거쳐 즉시 정제됩니다:
+모든 파일 이벤트는 4단계를 거쳐 처리됩니다:
 
 ```mermaid
 graph LR
@@ -85,138 +142,106 @@ graph LR
 
 | 단계 | 주요 동작 | 처리 속도 |
 |:------|:-----|:-----|
-| **Sense** | Chokidar 와처가 파일의 생성, 변경, 삭제를 즉각 감지 | < 10ms |
-| **Extract** | 면역 엔진이 내장된 3단계 건강 검진 실행 (IMM-001..003) | < 5ms |
-| **Adapt** | SQLite(WAL 모드) DB에서 최적의 복구 항체(Antibody) 매칭 | < 1ms |
-| **Mutate** | RFC 6902 JSON-Patch 기술로 원본 파일을 완벽히 복원 | < 25ms |
+| **Sense** | Chokidar 와처가 파일 생성, 변경, 삭제를 즉각 감지 | < 10ms |
+| **Extract** | 홀로그램(타입 뼈대) 생성 + 건강 검진 실행 | < 5ms |
+| **Adapt** | 증상-항체 매칭, 손상 파일 격리, 수정 전략 선택 | < 1ms |
+| **Mutate** | RFC 6902 JSON-Patch로 원본 파일 복원 | < 25ms |
 
-> **최종 성적표:** 파일 삭제 감지부터 복구 완료까지 **270ms 미만**.
+> 전체 사이클: 파일 삭제 감지부터 복구 완료까지 **270ms 미만**.
 
 ---
 
-## 🛠️ Magic 5 — 핵심 명령어
+## 명령어
+
+| 명령어 | 설명 |
+|:-------|:-----|
+| `afd start` | 스마트 탐색 + 데몬 가동 + 훅/MCP 자동 주입 |
+| `afd stop` | 근무 요약 리포트 + 안전한 종료 (`--clean`으로 훅/MCP 제거) |
+| `afd score` | 진화/홀로그램 통계 포함 건강 대시보드 |
+| `afd fix` | 홀로그램 컨텍스트 기반 진단 및 항체 학습 |
+| `afd sync` | 백신 페이로드 추출/가져오기 (`--push`, `--pull`, `--remote <url>`) |
+| `afd restart` | 종료 후 재시작 |
+| `afd status` | 빠른 건강 확인 — 데몬, 훅, MCP, 방어 현황 |
+| `afd doctor` | 종합 건강 분석 + 자동 수정 권고 |
+| `afd evolution` | 격리된 실패 분석 및 방지 규칙 생성 |
+| `afd mcp install` | MCP 서버를 프로젝트 + 글로벌 설정에 등록 |
+| `afd vaccine` | 커뮤니티 항체 조회, 설치, 발행 |
+| `afd lang` | 표시 언어 전환 (`afd lang ko` / `afd lang en`) |
 
-복잡한 건 빼고, 꼭 필요한 5가지만 담았습니다.
+---
 
-| 명령어 | 역할 | 핵심 지능 |
-|:-------|:-----|:----------|
-| `afd start` | **시동** | 백그라운드 데몬 가동 및 자동 훅 주입 |
-| `afd fix` | **수술** | 현재 프로젝트 진단 및 새로운 항체 학습 |
-| `afd score` | **대시보드** | 프로젝트 건강 점수 및 치유 통계 확인 |
-| `afd sync` | **전파** | 학습된 항체를 백신 파일로 추출 (팀 공유용) |
-| `afd stop` | **종료** | 데몬을 안전하게 끄고 프로세스 정리 |
+## 고급 기능
 
----
+### Double-Tap 휴리스틱
 
-## 📊 실시간 대시보드: `afd score`
+`afd`는 **실수**와 **의도**를 구분합니다:
 
 ```
-┌──────────────────────────────────────────────┐
-│  afd score — 프로젝트 건강 검진 리포트            │
-├──────────────────────────────────────────────┤
-│  에코시스템    : Claude Code                  │
-├──────────────────────────────────────────────┤
-│  가동 시간     : 1시간 23분                    │
-│  감지된 이벤트 : 156건                         │
-│  보호 중인 파일: 8개                          │
-├──────────────────────────────────────────────┤
-│  면역 시스템 상태 (Immune System)               │
-│  ──────────────────────────────              │
-│  보유 항체     : 7개                          │
-│  방어 레벨     : 철통 보안 (Fortified)          │
-│  자동 치유     : 3건 (백그라운드 처리)           │
-│  최근 치유     : IMM-003 (.claudeignore 복구)   │
-├──────────────────────────────────────────────┤
-│  억제 안전장치 (Safety)                        │
-│  ──────────────────────────────              │
-│  대규모 이벤트 무시: 2건 (git checkout 등)      │
-│  의도적 삭제 허용  : 0건 (Dormant 전환)         │
-├──────────────────────────────────────────────┤
-│  Hologram 절약   : 토큰 소모량 84% 감소         │
-└──────────────────────────────────────────────┘
+$ rm .claudeignore            # 1차 삭제 -> 즉시 복구
+$ rm .claudeignore            # 30초 내 재삭제 -> "진짜 지우고 싶구나?"
+  [afd] 사용자 의도 확인. 항체 IMM-001 휴면 전환. 삭제를 존중합니다.
 ```
 
----
+| 시나리오 | 대응 |
+|:---------|:-----|
+| 단일 삭제 (실수) | 자동 복구 + 첫 탭 기록 |
+| 30초 내 재삭제 (의도) | 항체 휴면, 삭제 존중 |
+| 1초 내 3건 이상 (git checkout) | 대규모 이벤트 감지, 억제 일시 정지 |
 
-## 💎 고도로 설계된 안전 장치
-
-### Double-Tap 휴리스틱 (의도와 실수의 구분)
-
-`afd`는 바보처럼 무조건 되살리지 않습니다. 사용자의 **진짜 의도**를 읽습니다:
+### 백신 네트워크
 
 ```bash
-$rm .claudeignore      # 1차 삭제: "실수인가 보군." -> 즉시 복구$ rm .claudeignore      # 60초 내 재삭제: "진짜 지우고 싶구나?" 
-  🛡️ [afd] 사용자 의도 확인. 항체 IMM-001 휴면 전환. 삭제를 존중합니다.
+afd sync              # .afd/global-vaccine-payload.json으로 추출
+afd sync --push       # 원격으로 백신 전파
+afd sync --pull       # 원격에서 백신 수신
 ```
 
-- **실수 방어:** 한 번의 삭제는 0.2초 만에 즉시 복구합니다.
-- **의도 존중:** 1분 내에 같은 파일을 또 지우면 사용자의 확고한 의지로 판단해 복구를 멈춥니다.
-- **Git 쇼크 방지:** `git checkout`처럼 수많은 파일이 한꺼번에 바뀌는 상황(1초 내 3개 이상)은 '대규모 이벤트'로 자동 인식하여 과도한 치유 동작을 멈춥니다.
-
-### 백신 네트워크 (팀 전파)
+페이로드는 정제되어 있어 기밀 정보가 포함되지 않습니다.
 
-나만 똑똑해지는 게 아닙니다. 내가 발견한 해결책을 팀원 모두에게 전파하세요:
+### 자가 진화
 
 ```bash
-afd sync
-# → .afd/global-vaccine-payload.json 생성
+afd evolution
 ```
-이 파일은 정제되어 있어 기밀 정보가 섞이지 않습니다. 다른 프로젝트에 넣기만 하면 `afd`가 해당 프로젝트의 면역력을 즉시 이식받습니다.
 
-### Hologram 추출 (토큰 다이어트)
-
-AI 에이전트가 파일 내용을 요구할 때, `afd`는 **뼈대만 남긴 초경량 요약본**을 제공합니다. 주석과 긴 함수 본문은 걷어내고 타입 정의와 구조만 전달하여 **토큰 비용을 80% 이상 절감**합니다.
+격리된 실패 사례를 분석하고 `afd-lessons.md`에 방지 규칙을 자동 기록합니다. AI 에이전트는 면역 파일 편집 전에 이를 읽어 과거의 실패를 미래의 예방책으로 전환합니다.
 
 ---
 
-## 🔌 Plugin / MCP 설정
-
-`afd`를 **Model Context Protocol (MCP) 서버**로 등록하면 Claude Code가 시작될 때 데몬이 자동으로 실행됩니다.
-
-### 자동 설정 (권장)
+## MCP 설정
 
-Claude Code MCP 설정(`~/.claude/mcp.json` 또는 프로젝트 `.mcp.json`)에 추가하세요:
+`afd`가 제공하는 MCP 도구와 리소스:
 
-```json
-{
-  "mcpServers": {
-    "afd": {
-      "command": "bun",
-      "args": ["run", "src/cli.ts", "start"]
-    }
-  }
-}
-```
-
-또는 포함된 매니페스트를 바로 복사하세요:
-
-```bash
-cp mcp-config.json .mcp.json
-```
+| MCP 도구 | 용도 |
+|:---------|:-----|
+| `afd_read` | 스마트 파일 리더 — 작은 파일은 원본, 큰 파일은 자동 홀로그램, 라인 범위 지원 |
+| `afd_hologram` | TS/JS 파일의 토큰 효율적 타입 뼈대 (80%+ 절감) |
+| `afd_diagnose` | 건강 진단 + 홀로그램 컨텍스트 |
+| `afd_score` | 런타임 통계: 가동시간, 치유 횟수, 홀로그램 절감률 |
 
-### 수동 실행
+| MCP 리소스 | 용도 |
+|:-----------|:-----|
+| `afd://workspace-map` | 전체 파일 트리 + export 시그니처를 한 번에 제공 |
 
 ```bash
-afd start   # 백그라운드 데몬 시작 및 훅 자동 주입
-```
-
-등록 후 Claude Code 상태 표시줄에서 실시간으로 확인할 수 있습니다:
-
-```
-🛡️ afd: ON | 🩹 3 Healed | last: IMM-003
+afd mcp install    # .mcp.json + ~/.claude.json에 자동 등록
 ```
 
 ---
 
-## 🛠️ 기술 스택
+## 기술 스택
 
-- **Runtime**: **Bun** — 초고속 실행 속도와 네이티브 SQLite 지원.
-- **Database**: **SQLite (WAL)** — 읽기 0.29ms의 압도적 성능과 크래시 안전성.
-- **Patching**: **RFC 6902 JSON-Patch** — 파일의 미세한 변화를 가장 정교하게 복원하는 기술.
+| 계층 | 기술 | 선택 이유 |
+|:-----|:-----|:----------|
+| 런타임 | **Bun** | 네이티브 TypeScript, 초고속 SQLite, 단일 바이너리 |
+| 데이터베이스 | **Bun SQLite (WAL)** | 읽기 0.29ms, 쓰기 24ms, 크래시 안전 |
+| 파일 감시 | **Chokidar** | 크로스플랫폼, 실전 검증된 와처 |
+| 패칭 | **RFC 6902 JSON-Patch** | 결정론적이고 조합 가능한 파일 변이 |
+| CLI | **Commander.js** | 표준적이고 예측 가능한 커맨드 파싱 |
 
 ---
 
-## 📦 설치 및 시작하기
+## 설치
 
 ```bash
 # Bun 사용 권장
@@ -224,26 +249,18 @@ bun install
 bun link
 afd start
 
-# 설치 없이 바로 실행하기 (npx)
+# 설치 없이 바로 실행 (npx)
 npx @dotoricode/afd start
 ```
 
 ### 환경 요구 사항
-- **Bun** >= 1.0
-- **OS**: Windows, macOS, Linux 지원
-- **호환 환경**: Claude Code, Cursor 등 (생태계 자동 감지)
-
----
 
-## 🛡️ 안도감을 주는 UX
-
-`afd`의 목표는 명확합니다.
-
-> **"설정 파일 하나 날아가서 30분을 허비하는 그런 날은 이제 끝났습니다."**
-
-당신은 코드에만 집중하세요. 프로젝트 환경의 건강은 `afd`가 24시간 백그라운드에서 지켜드립니다.
+- **Bun** >= 1.0
+- **OS**: Windows, macOS, Linux
+- **호환 환경**: Claude Code, Cursor, Windsurf, Codex (생태계 자동 감지)
 
 ---
 
 ## 라이선스
+
 MIT