feat(vision): 6점 비전 구현 — 의미검색 단계화·자동 관찰·지식 그래프·FTS

.claude/skills/agent-shared-context/SKILL.md

@@ -144,6 +144,17 @@ node tools/benchmark.mjs                # synthetic 5/50/500, writes BENCHMARK.m
 - 결론 + `refs`(검증 링크)만 저장. 다음 에이전트는 결론을 쓰거나 refs로 직접 확인
 - 버그는 `repro`에 재현 레시피만 (이것도 과정 로그가 아니라 레시피)
 
+## Auto-observability & FTS (v0.5.0)
+
+| 별칭 | 명령 | 동작 |
+|---|---|---|
+| /ac-watch | `node tools/ac-watch.mjs --since "1 day ago"` | git 이력에서 학습 후보 자동 감지 → .candidates/ (승격 전까지 비확정) |
+| /ac-promote | `node tools/ac-watch.mjs promote <file>` | 후보를 정식 디렉터리로 승격 |
+| /ac-fts | `node tools/ac-fts.mjs build/query/status` | SQLite FTS 백엔드 (Node ≥22.5 내장, 0 npm install) |
+| /ac-tasks | `node tools/benchmark-task.mjs` | 검색→정답 도달 과업 성공률 측정 |
+
+자동 관찰은 **후보만** 만든다 — 결론은 에이전트가 채워 넣어야 오염이 없다. 상세: `ROADMAP.md` `docs/session-continuity.md`.
+
 ## References
 
 - Concepts from `Coral-Protocol/AgentRadio` (Apache 2.0) and contemporary session collaboration patterns — file-based adaptation. See `docs/radio.md` `docs/sessions.md` `docs/hierarchy.md` `REFERENCES.md`.

BENCHMARK.md

@@ -16,9 +16,15 @@
 
 | scale | full tokens | avg top 3 tokens | avg saving | hitRate | avg latency (search) | est. full Read latency | tokens/hit |
 |---|---|---|---|---|---|---|
+<<<<<<< HEAD
+| 5 | 1315 | 178 | 83.1% | 80.0% | 0.11ms | 0.25ms (est. Read all md) | 223 |
+| 50 | 16780 | 761 | 94.7% | 85.0% | 0.40ms | 2.50ms (est. Read all md) | 895 |
+| 500 | 197940 | 1883 | 98.9% | 85.0% | 2.60ms | 25.00ms (est. Read all md) | 2216 |
+=======
 | 5 | 1315 | 178 | 83.1% | 80.0% | 0.16ms | 0.25ms (est. Read all md) | 223 |
 | 50 | 16780 | 761 | 94.7% | 85.0% | 0.41ms | 2.50ms (est. Read all md) | 895 |
 | 500 | 197940 | 1883 | 98.9% | 85.0% | 2.34ms | 25.00ms (est. Read all md) | 2216 |
+>>>>>>> fix/integration-defects
 
 ### Interpretation (critical, not hype)
 
@@ -30,11 +36,19 @@
 
 | query | assignedLevel | top tokens | saving | hit | latency |
 |---|---|---|---|---|
+<<<<<<< HEAD
+| auth | post-it | 45 | 99.7% | ✅ | 1.38ms |
+| api | post-it | 80 | 99.5% | ✅ | 0.33ms |
+| jwt | post-it | 0 | n/a (miss) | ❌ | 0.32ms |
+| pagination | post-it | 0 | n/a (miss) | ❌ | 0.31ms |
+| cache | post-it | 0 | n/a (miss) | ❌ | 0.36ms |
+=======
 | auth | post-it | 45 | 99.7% | ✅ | 0.39ms |
 | api | post-it | 80 | 99.5% | ✅ | 0.33ms |
 | jwt | post-it | 0 | n/a (miss) | ❌ | 0.89ms |
 | pagination | post-it | 0 | n/a (miss) | ❌ | 1.56ms |
 | cache | post-it | 0 | n/a (miss) | ❌ | 0.64ms |
+>>>>>>> fix/integration-defects
 
 ### What we learned while benchmarking (ideas & shortcomings →补)
 
@@ -65,7 +79,11 @@ No API key, no `npm install`, Node ≥18 only — like `agent-search-lite.mjs`.
     "avgTopTokens": 178,
     "avgSaving": "83.1%",
     "hitRate": "80.0%",
+<<<<<<< HEAD
+    "avgLatency": "0.11ms",
+=======
     "avgLatency": "0.16ms",
+>>>>>>> fix/integration-defects
     "fullLatencyEst": "0.25ms (est. Read all md)",
     "tokensPerHit": 223,
     "perQuery": [
@@ -75,7 +93,11 @@ No API key, no `npm install`, Node ≥18 only — like `agent-search-lite.mjs`.
         "topTokens": 50,
         "saving": "96.2%",
         "hit": true,
+<<<<<<< HEAD
+        "latency": "0.57ms"
+=======
         "latency": "0.65ms"
+>>>>>>> fix/integration-defects
       },
       {
         "query": "api",
@@ -107,7 +129,11 @@ No API key, no `npm install`, Node ≥18 only — like `agent-search-lite.mjs`.
         "topTokens": 0,
         "saving": "n/a (miss)",
         "hit": false,
+<<<<<<< HEAD
+        "latency": "0.05ms"
+=======
         "latency": "0.35ms"
+>>>>>>> fix/integration-defects
       }
     ]
   },
@@ -119,7 +145,11 @@ No API key, no `npm install`, Node ≥18 only — like `agent-search-lite.mjs`.
     "avgTopTokens": 761,
     "avgSaving": "94.7%",
     "hitRate": "85.0%",
+<<<<<<< HEAD
+    "avgLatency": "0.40ms",
+=======
     "avgLatency": "0.41ms",
+>>>>>>> fix/integration-defects
     "fullLatencyEst": "2.50ms (est. Read all md)",
     "tokensPerHit": 895,
     "perQuery": [
@@ -129,7 +159,11 @@ No API key, no `npm install`, Node ≥18 only — like `agent-search-lite.mjs`.
         "topTokens": 45,
         "saving": "99.7%",
         "hit": true,
+<<<<<<< HEAD
+        "latency": "1.38ms"
+=======
         "latency": "0.39ms"
+>>>>>>> fix/integration-defects
       },
       {
         "query": "api",
@@ -145,7 +179,11 @@ No API key, no `npm install`, Node ≥18 only — like `agent-search-lite.mjs`.
         "topTokens": 0,
         "saving": "n/a (miss)",
         "hit": false,
+<<<<<<< HEAD
+        "latency": "0.32ms"
+=======
         "latency": "0.89ms"
+>>>>>>> fix/integration-defects
       },
       {
         "query": "pagination",
@@ -161,7 +199,11 @@ No API key, no `npm install`, Node ≥18 only — like `agent-search-lite.mjs`.
         "topTokens": 0,
         "saving": "n/a (miss)",
         "hit": false,
+<<<<<<< HEAD
+        "latency": "0.36ms"
+=======
         "latency": "0.64ms"
+>>>>>>> fix/integration-defects
       }
     ]
   },
@@ -173,7 +215,11 @@ No API key, no `npm install`, Node ≥18 only — like `agent-search-lite.mjs`.
     "avgTopTokens": 1883,
     "avgSaving": "98.9%",
     "hitRate": "85.0%",
+<<<<<<< HEAD
+    "avgLatency": "2.60ms",
+=======
     "avgLatency": "2.34ms",
+>>>>>>> fix/integration-defects
     "fullLatencyEst": "25.00ms (est. Read all md)",
     "tokensPerHit": 2216,
     "perQuery": [
@@ -183,41 +229,77 @@ No API key, no `npm install`, Node ≥18 only — like `agent-search-lite.mjs`.
         "topTokens": 45,
         "saving": "99.9%+",
         "hit": true,
+<<<<<<< HEAD
+        "latency": "5.40ms"
+=======
         "latency": "3.82ms"
+>>>>>>> fix/integration-defects
       },
       {
         "query": "api",
         "assignedLevel": "post-it",
         "topTokens": 45,
         "saving": "99.9%+",
         "hit": true,
+<<<<<<< HEAD
+        "latency": "2.38ms"
+=======
         "latency": "1.83ms"
+>>>>>>> fix/integration-defects
       },
       {
         "query": "jwt",
         "assignedLevel": "post-it",
         "topTokens": 0,
         "saving": "n/a (miss)",
         "hit": false,
+<<<<<<< HEAD
+        "latency": "2.32ms"
+=======
         "latency": "6.05ms"
+>>>>>>> fix/integration-defects
       },
       {
         "query": "pagination",
         "assignedLevel": "post-it",
         "topTokens": 0,
         "saving": "n/a (miss)",
         "hit": false,
+<<<<<<< HEAD
+        "latency": "2.66ms"
+=======
         "latency": "4.64ms"
+>>>>>>> fix/integration-defects
       },
       {
         "query": "cache",
         "assignedLevel": "post-it",
         "topTokens": 0,
         "saving": "n/a (miss)",
         "hit": false,
+<<<<<<< HEAD
+        "latency": "2.46ms"
+=======
         "latency": "4.53ms"
+>>>>>>> fix/integration-defects
       }
     ]
   }
 ]
 ```
+
+## Task-success benchmark (#4 프록시)
+
+```json
+{
+  "metric": "retrieval-task success (proxy for agent task success)",
+  "tasks": 3,
+  "accuracy": "100.0%",
+  "avgTokensPerTask": 88,
+  "flatReadTokensPerTask": 265,
+  "savingVsFlat": "66.7%",
+  "honesty_note": "이 수치는 \"검색→정답 파일 도달\" 프록시다. 실제 작업 성공률(버그 수정 등)은 라이브 에이전트 하네스 필요 — ROADMAP P1."
+}
+```
+
+> 실행: `node tools/benchmark-task.mjs`. 위 지표는 "질의→정답 파일 도달" 프록시이며, 실제 작업 성공률은 라이브 에이전트 하네스 과제 (ROADMAP P1).

README.md

@@ -10,14 +10,14 @@
 | 시나리오 | 전체 읽기 | 이 프로젝트 사용 | 절약 | 히트율 |
 |---|---|---|---|---|
 | 검색 5개 | 5,280 tok | 1,040 tok | **80%** | 80% |
-| 검색 50개 | 25,580 tok | 1,758 tok | **93%** | 85% |
+| 검색 50개 | 25,580 tok | ~1,760 tok | **~94%** | 85% |
 | 검색 500개 | 194,800 tok | 2,003 tok | **99%** | 85% |
-| **세션 복원** 500개 | 191,825 tok (재독입) | **3,460 tok** (핸드오프) | **98%**, 손실 0 | — |
+| **세션 복원** 500개 | 191,825 tok (재독입) | **3,460 tok** (핸드오프) | **98%**, 구조적 손실 0* | — |
 
-*세션 복원: 압축(compaction) 없이 `CURRENT.md` + 핸드오프 포인터 번들로 새 세션이 ~600 tok 만에 기존 작업을 이어받음. 상세는 `docs/session-continuity.md`.*
+*세션 복원: 압축 없이 포인터 번들로 복원. \*구조적 손실 0 — 단, entry로 저장한 것만 보장됨. 저장하지 않은 논의는 사라짐(저장 성실성이 전제).*
 
 - **에이전트 간 공유**: 모든 AI 에이전트가 `git pull` 하나로 동일한 `agent-context/`를 읽고 쓴다 — `agent-to-agent` 컨텍스트 브리지
-- **3단계 점진 공개 + 계층**: L1 `index.json` → L2 `graph.json`/`features.json` → L3 `*.md` 1~2개, 가벼운 AI가 `post-it`(15tok)→`library`(5000tok) 중 시작점 자동 결정
+- **3단계 점진 공개 + 계층**: L1 `index.json` → L2 `graph.json`/`features.json` → L3 `*.md` 1~2개, 규칙 기반 휴리스틱 라우터(LLM 호출 0)가 `post-it`(15tok)→`library`(5000tok) 중 시작점 자동 결정 — "가벼운 AI"는 휴리스틱을 의미
 - **서브에이전트 불필요**: 모든 도구가 단일 Bash 호출 — 메인 에이전트가 직접 검색, Node 없으면 순수 Grep/Read 폴백까지 동작
 - **Git이 곧 DB**: PR 리뷰·`git blame` 가능, 모든 agent가 `git pull`로 동기화
 - **학습 루프**: `learnings`의 `cause/fix/lesson`으로 실패 반복 방지
@@ -26,6 +26,17 @@
 
 **Muse Spark 1.2 Agent** (`opencode/muse-spark-1.2-contributor-free`, Meta Muse Spark via OpenCode) — 설계·구현·벤치마크·후기(`REVIEW.md`) 전부 이 에이전트가 직접 수행. 환경 상세는 `AGENT.md` `docs/agent-environment.md`.
 
+## Architecture (4 layers — 경계 명시)
+
+| Layer | 책임 | 위치 |
+|---|---|---|
+| **Context Store** | 기억의 정본 저장 | `agent-context/*.md` + `index/graph/features.json` |
+| **Retrieval** | 계층적 검색·레벨 배정 | `tools/agent-search-lite.mjs` + `agent-context-index.mjs` |
+| **Handoff** | 세션 연속성 | `tools/agent-handoff.mjs` + `CURRENT.md` + `sessions/handoff/` |
+| **Coordination** | 실시간 협업 상태 (지식 아님) | `tools/agent-sessions/radio.mjs` + `sessions/inbox/` + `radio/threads/` |
+
+Coordination은 지식을 만들지 않는다 — live 메시지는 로컬에서 소비되고, 지식화 가치가 있을 때만 entry→PR로 승격된다. 이 경계를 지키는 것이 기능 팽창 방지의 핵심이다.
+
 ## 빠른 시작
 
 ```bash
@@ -241,6 +252,8 @@ cp -r skills/agent-shared-context ~/.codex/skills/
 
 **결과 중심 기록 원칙**: 도구 호출 로그 저장 금지 — 결론 + refs(검증 링크)만. 토큰 낭비 제거.
 
+**자동 관찰(v0.5)**: `node tools/ac-watch.mjs` — git 이력에서 학습 후보를 자동 생성(.candidates/, proposed). 승격 전까지 비확정으로 오염 방지. `ROADMAP.md` 참조.
+
 ## 검증
 
 ```bash

ROADMAP.md

@@ -0,0 +1,48 @@
+<!-- Path: ROADMAP.md -->
+# Roadmap — 6점 비전 반영 현황 (외부 리뷰·사용자 제안 통합)
+
+> 각 항목은 **채택/부분/보류**와 근거를 함께 기록한다. 전부 지금 하면 zero-install 철학이 무너지므로, 순서가 설계의 일부다.
+
+## #1 규칙 기반 → 의미 이해 — **부분 완료, 단계적 확장**
+
+| 단계 | 상태 | 내용 |
+|---|---|---|
+| 1a 동의어 확장 | ✅ v0.4.x | config `search.synonyms` — jwt↔token 등, 0 LLM. `token authentication` → JWT entry 히트 실측 |
+| 1b 필드 가중치(BM25-lite) | ✅ v0.5.0 | 제목×3 태그×2 피처×2 요약×1 — naive includes 대비 랭킹 품질 향상 |
+| 1c 로컬 임베딩 | 🔶 opt-in 어댑터 | `search.semantic.enabled=true` 시 `@xenova/transformers` 동적 로드. **미설치면 실행조차 안 하고** `router.semantic`에 unavailable 사유 정직 표기 후 휴리스틱 폴백. 기본 OFF — "0-install 셀링포인트 유지"가 트레이드오프 결론 |
+
+"가벼운 AI" 표현은 외부 리뷰 지적대로 **규칙 기반 휴리스틱 라우터**로 문서 전반에 명확히 표기했다.
+
+## #2 수동 기록 → 자동 관찰 — **부분 완료 (후보 생성 방식)**
+
+- 결과 중심 기록 원칙과 자동화는 **모순이 아니라 직렬**이다: 자동화는 *원시 신호*를 모으고, 결과 중심 원칙은 *승격된 기억*의 형식을 강제한다.
+- 구현: `tools/ac-watch.mjs` — git 이력에서 R1 fix-signal / R2 test+src co-change / R3 대형 변경 / R4 decision-word를 감지해 `.candidates/`에 **후보** 생성 (0 LLM). 실측: 최근 7일 커밋에서 12건 후보.
+- 오염 방지: 후보는 `status: proposed`, `epistemic: observed`로 자동 확정되지 않음. 에이전트가 결론을 덧붙인 뒤 `promote`해야 정식 기억.
+
+## #3 파일 → 지식 그래프 — **기반 완료, 심화는 P1**
+
+- `index.json.knowledge.edges[]`: related[]에서 유추한 인과 엣지 (`bug→learning=mitigates/caused_by`, `decision supersedes`, `idea adopted_from`, `code-history implements`).
+- 현재는 1-hop 유추. P1: supersedes 체인 전개로 "이 결정이 왜 뒤집혔나" 질의 지원, graph.json과 병합.
+
+## #4 토큰 벤치마크 → 작업 성공률 — **프록시 하네스 완료, 실전 과제는 P1**
+
+- `tools/benchmark-task.mjs`: 질의→정답 파일 도달율(retrieval-task accuracy) + 과업당 토큰 측정. 현재 소규모 실측: accuracy 100%, 88 tok/task (표본 3 — 한계 명시).
+- 정직한 선언: 이것은 프록시다. AgentRadio식 실작업 성공률(버그 수정 성공) 비교는 라이브 에이전트 하네스가 필요하며 P1 과제로 남긴다.
+
+## #5 실사용 규모 검증 — **도구 준비 완료, 운영 축적 필요**
+
+- 장기 운영 문제(오래된 기억 vs 최신 결정 모순)의 첫 도구: `index.json.stale{}` — priority≥4 · 90일 경과 항목 리포트.
+- 진짜 답은 시간이 필요하다: 수백~수천 entry, 다중 에이전트 운용 데이터가 쌓여야 검증된다. ROADMAP상 P1 유지.
+
+## #6 JSON → SQLite — **선택 백엔드 완료 (Node 내장, 0 npm install)**
+
+- `tools/ac-fts.mjs`: Node ≥22.5 내장 `node:sqlite`로 FTS5 build/query/status. better-sqlite3 불필요.
+- 미지원 환경(Node 20 등)은 JSON+Grep 폴백이 **기능 손실 없이** 계속 동작 — 전환 임계는 entries 300+ 권장.
+
+## 우선순위 (외부 리뷰 P0/P1/P2 재편성)
+
+- ~~P0 retrieval recall~~ → 1a·1b 완료, 1c opt-in
+- ~~P0 provenance~~ → schema `epistemic/source/verified_by` (v0.4.1), watch 후보는 `observed`로 자동 부여
+- ~~P0 concurrency~~ → index atomic write(tmp+rename), 6-프로세스 병령 스모크 테스트 통과
+- P1 실전 벤치마크 / decision graph 심화 / E2E CI 유지보수
+- P2 vector DB·MCP server — 당분간 보류 (zero-install 철학)

agent-context.config.json

@@ -192,6 +192,35 @@
       "diary",
       "bookshelf",
       "library"
-    ]
+    ],
+    "synonyms": {
+      "jwt": [
+        "token"
+      ],
+      "token": [
+        "jwt"
+      ],
+      "auth": [
+        "authentication",
+        "인증"
+      ],
+      "authentication": [
+        "auth"
+      ],
+      "bug": [
+        "issue",
+        "버그"
+      ],
+      "issue": [
+        "bug"
+      ],
+      "race": [
+        "경쟁조건"
+      ],
+      "pagination": [
+        "페이지네이션",
+        "cursor"
+      ]
+    }
   }
 }

agent-context/.candidates/024d4e63ea-work-history.md

@@ -0,0 +1,30 @@
+<!-- Path: agent-context/.candidates/024d4e63ea-work-history.md -->
+---
+id: candidate-mta1gas1
+type: work-history
+level: ""
+title: "feat(continuity): 세션 압축 대체 핸드오프 — 손실 0·저토큰 복원, 서브에이전트 불필요"
+tags: [candidate, auto-watch]
+feature: global
+scope: global
+agent: system
+created: 2026-08-26T11:56:39.697Z
+updated: 2026-08-26T11:56:39.697Z
+status: proposed
+priority: 2
+epistemic: observed
+summary: "[auto-candidate] R3 large change: 684 insertions. 사람/에이전트가 결론을 덧붙여 승격 필요."
+refs:
+  - "commit:024d4e63ea"
+---
+
+## 감지 근거
+R3 large change: 684 insertions (684 insertions)
+
+## 다음 단계 (에이전트가 수행)
+
+1. 아래 결론을 채워 넣고 status: proposed → done
+
+2. `node tools/ac.mjs index` 재생성
+
+3. 파일을 정식 디렉터리로 이동: `code-history/`