ltcai 9.8.0 → 9.9.1

package/docs/OPERATIONS.md

@@ -1,13 +1,18 @@
-# Lattice AI — Operations Guide (v9.6.0)
+# Lattice AI — Operations Guide (v9.9.1)
+
+> **Status: canonical** — kept in sync with the current release. Storage layout
+> below reflects the SQLite live Brain store and workspace scoping, not the
+> earlier Markdown-per-node graph.
 
 ## 1. 데이터 파일 위치
 
 | 파일 | 용도 |
 |------|------|
 | `~/.ltcai/users.json` | 사용자 계정 (scrypt 해시 저장) |
-| `~/.ltcai/history.json` | 대화 히스토리 |
+| `~/.ltcai/knowledge_graph.sqlite` | Brain 라이브 스토어 — Knowledge Graph 노드/엣지/청크, 대화 히스토리, 프로비넌스 (workspace_id 스코프) |
+| `~/.ltcai/knowledge_graph_blobs/` | 업로드 원본/blob 저장소 |
 | `~/.ltcai/audit.json` | 감사 로그 (agent 실행, 사용자 변경 등) |
-| `~/.ltcai/brain/` | Knowledge Graph 노드 (Markdown) |
+| `~/.ltcai/chat_history.json` | 레거시 대화 히스토리 — 최초 1회 SQLite로 idempotent 임포트 후 미사용 |
 | `~/ltcai-agent/` | Agent workspace (agent가 생성한 파일) |
 
 ## 2. 백업 및 복구
@@ -112,8 +117,10 @@ pip install --upgrade ltcai
 
 ### 6.3 데이터 마이그레이션 주의사항
 - `users.json` 스키마 변경 시: 서버가 자동으로 누락 필드를 기본값으로 보완합니다.
-- `history.json` 스키마 변경 시: 하위 호환성 유지. 구버전 레코드는 무시됩니다.
-- `brain/` Knowledge Graph: Markdown 파일 기반이므로 별도 마이그레이션 없음.
+- 대화 히스토리: SQLite 라이브 스토어에 저장됩니다. 레거시 `chat_history.json`은
+  최초 실행 시 1회 idempotent 임포트된 뒤 사용되지 않습니다.
+- `knowledge_graph.sqlite` Knowledge Graph: SQLite 스키마 마이그레이션은 부팅 시
+  적용되며 읽기 호환성/롤백/동등성 테스트로 보호됩니다.
 
 ## 7. 공개 서버 체크리스트
 
@@ -135,7 +142,9 @@ pip install --upgrade ltcai
 - 대화 히스토리는 `user_email` 필드로 필터링됩니다.
 - Agent workspace (`~/ltcai-agent/`)는 현재 단일 공유 디렉토리입니다.  
   멀티 유저 환경에서는 `~/ltcai-agent/<email>/` 구조로 분리를 권장합니다.
-- Knowledge Graph (`brain/`) 역시 단일 공유 공간입니다.
+- Knowledge Graph는 `workspace_id`로 스코프됩니다. 알 수 없는 스코프의 노드는
+  기본 비공개(fail-closed)이며, 레거시 글로벌 읽기는 명시적 호환성 옵트인이
+  있을 때만 허용됩니다.
 
 ## 9. 서버 시작 / 종료
 

package/docs/PERFORMANCE.md

@@ -1,5 +1,13 @@
 # Knowledge Graph Performance Baseline
 
+> **Status: reference** — a synthetic regression baseline, not a
+> current-release measurement. The numbers below were last captured on the
+> v9.6.0 working tree (see provenance line) and are carried forward as the
+> comparison reference. The 9.7.0-9.8.0 line added graph-layer paths
+> (`hybrid_search`, vector freshness, extraction-quality scoring), so
+> regenerate with `scripts/profile_kg.py` on the current tree before treating
+> these as 9.8.0 numbers.
+
 Synthetic performance and memory baseline for `KnowledgeGraphStore`
 (`lattice_brain/graph/`). Measured with `scripts/profile_kg.py`.
 
@@ -34,7 +42,7 @@ Run it:
 .venv/bin/python scripts/profile_kg.py --json          # machine-readable
 ```
 
-## Measured baseline (2026-07-20, v9.6.0 working tree)
+## Measured baseline (last captured on the v9.6.0 working tree)
 
 Apple Silicon (darwin), Python 3.x from `.venv`, SQLite with FTS5 trigram
 available, tracemalloc enabled.

package/docs/SECURITY_AUDIT.md

@@ -0,0 +1,91 @@
+# Security Audit — Static Scan Snapshot
+
+> Status: audit snapshot 2026-07-21
+
+This is a point-in-time static-analysis snapshot for release **v9.8.0**. It
+records exactly which scanners ran, the raw findings, and an honest per-finding
+real-risk assessment. It is not a guarantee of absence of vulnerabilities; it is
+evidence of what the listed tools saw on the listed date.
+
+Related: [CI & Release Gates](CI_AND_RELEASE_GATES.md) documents how these scans
+are wired into continuous integration (`.github/workflows/dependency-audit.yml`).
+
+## Tooling & commands
+
+Scanners were installed into the project virtualenv only (`.venv`), never added
+to runtime dependencies:
+
+```
+.venv/bin/python -m pip install pip-audit bandit
+```
+
+| Tool      | Version | Command |
+|-----------|---------|---------|
+| pip-audit | 2.10.1  | `.venv/bin/python -m pip_audit -r requirements.txt --strict` |
+| pip-audit | 2.10.1  | `.venv/bin/python -m pip_audit` (installed environment) |
+| bandit    | 1.9.4   | `.venv/bin/python -m bandit -r latticeai lattice_brain -ll` |
+| npm audit | (npm 10)| `npm audit --audit-level=high` |
+
+## Dependency vulnerabilities (pip-audit / npm audit)
+
+**Result: no known vulnerabilities.**
+
+- `pip-audit -r requirements.txt --strict` → `No known vulnerabilities found`.
+- `pip-audit` over the installed environment → `No known vulnerabilities found`.
+- `npm audit --audit-level=high` → `found 0 vulnerabilities`.
+
+No dependency version changes were required. Because there were no actual
+vulnerable pins to fix, no dependency files were modified (per the honest-fix
+rule: only fix a real, safe-to-fix issue).
+
+## Static code analysis (bandit)
+
+Scanned **54,795 lines** across `latticeai/` and `lattice_brain/`. With the
+`-ll` display filter (MEDIUM severity and above), bandit reported **80 findings**:
+1 HIGH and 79 MEDIUM. Breakdown by rule:
+
+| Count | Severity | Rule | What it flags |
+|------:|----------|------|---------------|
+| 1  | HIGH   | B324 hashlib | Weak MD5 hash "for security" |
+| 58 | MEDIUM | B608 hardcoded_sql_expressions | SQL built via string formatting |
+| 7  | MEDIUM | B310 blacklist (urlopen) | `urllib.request.urlopen` with unrestricted scheme |
+| 5  | MEDIUM | B604 shell=True | A function called with `shell=True` |
+| 3  | MEDIUM | B108 hardcoded_tmp_directory | Hardcoded `/tmp` path |
+| 3  | MEDIUM | B104 hardcoded_bind_all_interfaces | Bind to `0.0.0.0` |
+| 2  | MEDIUM | B306 blacklist (mktemp) | `tempfile.mktemp()` |
+| 1  | MEDIUM | B615 huggingface_unsafe_download | `hf_hub_download` without a pinned revision |
+
+### Per-finding real-risk assessment
+
+| Rule | Location(s) | Verdict | Rationale |
+|------|-------------|---------|-----------|
+| **B324** MD5 | `lattice_brain/quality.py:44` | **False positive** | MD5 derives a deterministic *pseudo-label* for embedding clusters (`emb_cluster_<hash>`); not used for authentication, integrity, or secrets. Safe cosmetic fix would be `hashlib.md5(..., usedforsecurity=False)`; source is out of this task's edit scope, so documented only. |
+| **B604** shell=True | `latticeai/core/agent.py:539`, `latticeai/core/tool_registry.py:129/136/168/175` | **False positive** | These are `ToolPolicy(..., shell=True, ...)` dataclass *declarations* describing whether a tool is a shell tool — not `subprocess(..., shell=True)` calls. Bandit matches the keyword, not an actual shell invocation. |
+| **B108** /tmp | `lattice_brain/graph/_kg_constants.py:186/215`, `latticeai/core/agent_eval.py:240` | **False positive / benign** | The `_kg_constants` hits are `/tmp` entries in an **exclusion allowlist** of directories to skip during ingestion (a defensive list). The `agent_eval` hit is a test/eval default `agent_root`. No untrusted file is written to a predictable temp path here. |
+| **B104** 0.0.0.0 | `latticeai/cli/entrypoint.py:53/237/238` | **By design, low risk** | The bind switches to `0.0.0.0` only when the operator explicitly passes `--tunnel`; default remains `127.0.0.1`. Intentional and gated. |
+| **B310** urlopen | `latticeai/services/model_engines.py:120/234`, `latticeai/services/model_runtime.py:242` | **Low real risk** | Calls target operator-configured local inference engines (LM Studio / Ollama). URLs are not attacker-controlled in normal use. Recommendation: assert `http(s)` scheme before `urlopen` to close the `file:`/custom-scheme door. |
+| **B608** SQL f-strings | `lattice_brain/storage/postgres.py`, `.../migration.py`, `lattice_brain/graph/*.py`, `lattice_brain/conversations.py` | **Low real risk — review** | Interpolated fragments are overwhelmingly **schema/table identifiers** quoted through `lattice_brain.storage.postgres._quote_ident`, with row *values* passed as bound parameters. Not user-value injection. Standing recommendation: keep every interpolated identifier sourced from internal constants / allowlists, never from request input. |
+| **B306** mktemp | `latticeai/integrations/telegram_bot.py:450/568` | **Real, low severity** | `tempfile.mktemp()` has a documented create-time race; prefer `tempfile.mkstemp()` / `NamedTemporaryFile`. Impact is limited (local temp files for outbound Telegram media), but this is a genuine hardening item for a future source-owning change. |
+| **B615** HF download | `latticeai/services/model_runtime.py:601` | **Real, supply-chain relevant** | `hf_hub_download(...)` is called without `revision=`, so a mutated upstream model repo could serve a different artifact than expected. Recommendation: pin a commit/`revision` (or verify a hash) when fetching model weights. Ties directly into the P2 supply-chain theme. |
+
+## Actions taken vs deferred
+
+- **Fixed:** nothing — no dependency vulnerability existed to fix safely, and
+  the code-level findings live in source files outside this task's edit scope.
+- **Deferred (documented) hardening items**, for a future change that owns the
+  relevant source:
+  1. Pin a `revision` in `model_runtime.py` `hf_hub_download` (B615).
+  2. Replace `tempfile.mktemp()` in `integrations/telegram_bot.py` (B306).
+  3. Validate URL scheme before `urlopen` in the model engine paths (B310).
+  4. Optional cosmetic: `usedforsecurity=False` on the clustering MD5 (B324).
+
+## Limitations (honest)
+
+- Static analysis only. No dynamic/DAST, no fuzzing, no secret-scanning here.
+- bandit reasons syntactically; the false positives above were confirmed by
+  reading each site, not by suppression.
+- pip-audit resolves against the OSV/PyPI advisory database as of the snapshot
+  date; new advisories appear continuously — see the scheduled
+  `dependency-audit` workflow for the ongoing signal.
+- SBOMs (CycloneDX) for both ecosystems can be regenerated with
+  `.venv/bin/python scripts/generate_sbom.py`.

package/docs/TRUST_MODEL.md

@@ -1,6 +1,6 @@
 # Lattice AI Trust Model
 
-Current release: **9.8.0 — Honest Knowledge Pipeline**.
+Current release: **9.9.1 — Clean Foundations**.
 
 Lattice AI is local-first, explicit about external communication, and honest
 when a capability is unavailable.

package/docs/USABILITY_AUDIT.md

@@ -0,0 +1,164 @@
+# Usability Heuristic Audit
+
+> Status: audit snapshot 2026-07-21
+
+A heuristic (expert) evaluation of the Lattice AI product surface against
+Jakob Nielsen's 10 usability heuristics, focused on the five journeys called out
+in external review: **device analysis**, **agent completion**, **change
+approval**, **Brain hierarchy**, and **slow first run**.
+
+**This is not a substitute for real-user testing.** Heuristic evaluation finds
+plausible problems from an expert's read of the code and UI; it cannot measure
+what real users actually do, misread, or abandon. Every recommendation below
+should be validated with 5–8 real sessions before it is treated as fact.
+
+Evidence is cited as `file:line` against the frontend source
+(`frontend/src/**`, TypeScript/React) and Python services. Note the shipped
+`static/app/assets/*.js` is a minified bundle and is not citable line-by-line;
+citations point at the readable source it is built from.
+
+## Journey 1 — Device analysis (onboarding)
+
+Surface: `frontend/src/components/onboarding/AnalysisScreen.tsx`; backing logic
+`latticeai/services/model_recommendation.py`.
+
+- The screen renders **real detected facts**, not pure theater: it maps over a
+  `analysis` prop and shows real RAM when available
+  (`AnalysisScreen.tsx:18`, `:95` — `ramGb ? \`${Math.round(ramGb)} GB\``).
+- RAM sizing and Apple-Silicon detection are honest, documented estimates:
+  `estimated_ram_gb = size_gb * 1.25 + 2.5` (`model_recommendation.py:64`),
+  `is_apple_silicon` (`:69`), `recommend_catalog` (`:160`).
+
+Heuristics:
+- **#1 Visibility of system status** — GOOD: hardware line items begin in a
+  `flow.analysis.checking` state (`AnalysisScreen.tsx:63-67`) then resolve to
+  detected values, so the scan reads as progress rather than a frozen screen.
+- **#2 Match to the real world** — GOOD: plain-language labels (chip, RAM, GPU,
+  support, models) via i18n keys rather than jargon.
+- **#1 risk** — the staged "checking → detected" reveal is presentation timing,
+  not the true probe duration; if detection is effectively instant, the delay is
+  cosmetic. Recommend: keep the animation only as long as real work is pending,
+  and label any assumed/estimated value (e.g. RAM heuristic) as an estimate so
+  users don't read `~16 GB` as a precise measurement.
+
+## Journey 2 — Agent completion
+
+Surface: `latticeai/core/agent.py`.
+
+- Terminal states are explicit: `DONE`, `FAILED`, `NEEDS_REVIEW`
+  (`agent.py:50-56`), and a user-facing `final_message` is always set
+  (`:307`, and the default `"작업을 완료했습니다."` at `:357`).
+
+Heuristics:
+- **#1 Visibility of system status** — GOOD: the loop distinguishes *completed*
+  from *needs-review* from *failed*, so the UI can tell the user which of three
+  very different outcomes occurred instead of a generic "done".
+- **#9 Help users recognize/recover from errors** — GOOD structurally: parse
+  slips are traced with a `recovered` flag (`agent.py:255`, `:439-441`), so the
+  system can surface "I had to retry" honestly.
+- **Recommendation** — ensure the frontend actually renders the *distinction*
+  between `DONE` and `NEEDS_REVIEW` prominently (color + copy), not just the
+  `final_message` string; a review-required outcome that looks like success is a
+  **#1/#5** hazard (user thinks work shipped when it is only staged).
+
+## Journey 3 — Change approval
+
+Surface: `latticeai/services/change_proposals.py`, gate entry
+`latticeai/core/agent.py:273` (`approve`).
+
+- Mutations of existing content are **staged, not applied**: `review(...)`
+  returns `{"decision": "proposed", ...}` with a proposal record
+  (`change_proposals.py:124`, `:177`), and application is a separate explicit
+  `approve_and_apply` (`:347`). Additive creates flow with less friction.
+
+Heuristics:
+- **#3 User control & freedom** — STRONG: proposal-first governance means a
+  destructive/edit action is reversible-by-default (it hasn't happened yet).
+  This is the best-defended journey of the five.
+- **#5 Error prevention** — STRONG: the split between additive (`allow_additive`)
+  and mutating (`proposed`) is exactly the guardrail #5 asks for.
+- **#10 Help & documentation / #2 match** — RISK: the value only lands if the
+  approval UI explains *what changes* and *why it was staged* in plain language.
+  Recommend a per-proposal diff + one-line "why this needs your review" derived
+  from the `classification`/`reason` provenance already stored
+  (`change_proposals.py:237`), so approval is an informed decision, not a blind
+  "OK".
+
+## Journey 4 — Brain hierarchy
+
+Surface: `frontend/src/features/brain/DepthEmergence.tsx`,
+`.../BrainMemoryLayer.tsx`.
+
+- The Brain reveals structure **progressively by depth**: nothing at depth 1,
+  memory layer at depth ≥2, knowledge layer at depth ≥3, higher structure at
+  depth ≥4 (`DepthEmergence.tsx:29`, `:33-39`); the memory layer caps visible
+  nodes by depth (`BrainMemoryLayer.tsx:16`).
+
+Heuristics:
+- **#8 Aesthetic & minimalist design** — GOOD intent: progressive disclosure
+  avoids dumping the full graph on a new user.
+- **#6 Recognition rather than recall** — RISK: depth is an abstract control. A
+  user may not know what "depth 3" means or that concepts appear only there.
+  Recommend naming each tier (e.g. "Memories → Concepts → Connections") and
+  showing the current tier label, so the hierarchy is recognizable, not a hidden
+  numeric mode.
+- **#7 Flexibility & efficiency** — RISK: capping visible nodes (6–8) aids
+  focus but can hide relevant memory with no "show more" affordance; verify an
+  expansion path exists for power users.
+
+## Journey 5 — Slow first run
+
+Surface: `frontend/src/components/onboarding/InstallScreen.tsx`,
+`.../DownloadConsentPanel.tsx`; backing `latticeai/services/model_runtime.py`.
+
+- First run is staged and streamed: `InstallStage` = idle→install→download→
+  validate→load→done (`InstallScreen.tsx:12`), a live `percent` bar
+  (`:28`, `:44`, `:119`) fed by `streamModelPrepare` (`:38`), plus an up-front
+  time estimate line (`:86`, `expectedLine` at `:158` using
+  `estimatedDownloadMinutes` / `estimatedFirstResponseSeconds`).
+- Download size and consent are disclosed **before** the download begins
+  (`DownloadConsentPanel.tsx:9`, `:18-24`).
+
+Heuristics:
+- **#1 Visibility of system status** — STRONG: staged progress + percent + ETA
+  is close to the textbook remedy for a long wait; the slow first run is
+  *communicated*, not silent.
+- **#5 Error prevention / #3 control** — GOOD: size + consent before a large
+  download respects the user's bandwidth and choice.
+- **RISK** — the ETA is a static estimate from catalog metadata
+  (`estimatedDownloadMinutes`), not a live-adjusted projection; on a slow link
+  the bar can stall while the estimate reads optimistically. Recommend deriving
+  a live ETA from observed `event.percent` throughput and clearly marking the
+  initial number as an estimate. Also confirm a **failure** path exists on the
+  `error` stage (`InstallScreen.tsx:12`) with a retry, not a dead end (#9).
+
+## Cross-cutting findings
+
+- **#4 Consistency & standards** — i18n has an explicit ko/en fallback discipline
+  (e.g. `brain.sources.fallback` in both `frontend/src/i18n/brain.ts:643` and
+  `:1301`). Keep en/ko key parity enforced (the repo already has an i18n literal
+  check) so no screen silently falls back to Korean for an English user.
+- **#10 Documentation** — onboarding leans on progressive UI over docs, which is
+  good, but the abstract controls (Brain depth) would benefit from inline
+  first-use hints.
+
+## Priority recommendations (heuristic — validate with real users)
+
+1. **Make `NEEDS_REVIEW` visually distinct from `DONE`** in agent completion
+   (Journey 2) — highest risk of a false "it shipped" mental model.
+2. **Show a diff + plain-language "why staged" on every change proposal**
+   (Journey 3) so approval is informed.
+3. **Name the Brain hierarchy tiers and show the current tier** (Journey 4) to
+   convert an abstract depth control into recognizable structure.
+4. **Live-adjust the first-run ETA and label estimates as estimates**
+   (Journeys 1 & 5).
+5. **Verify the install `error` stage offers a retry** (Journey 5, #9).
+
+## Limitations (honest)
+
+- Expert heuristic evaluation only; no real users, no task-success metrics, no
+  time-on-task, no accessibility audit (screen-reader/keyboard) beyond noting
+  `aria-hidden` usage.
+- Frontend runtime behavior was inferred from source, not driven live in this
+  pass; timing/animation claims should be confirmed in a running build.
+- Severity is the evaluator's judgment, not a measured frequency × impact.

package/docs/WHY_LATTICE.md

@@ -1,6 +1,6 @@
 # Why Lattice AI Exists
 
-Current release: **9.8.0 — Honest Knowledge Pipeline**.
+Current release: **9.9.1 — Clean Foundations**.
 
 **Lattice AI is a local-first Digital Brain that keeps your knowledge durable
 across any AI model.**

package/docs/architecture.md

@@ -1,8 +1,10 @@
 # Lattice AI Architecture
 
-> Historical subsystem note. The canonical current architecture document is
+> **Status: historical** — subsystem note preserved for background. The
+> canonical current architecture document is
 > [`ARCHITECTURE.md`](../ARCHITECTURE.md). This file preserves the v3.6.0
-> Knowledge Graph First architecture detail for background.
+> Knowledge Graph First architecture detail; its version and subsystem claims
+> are intentionally frozen at that point in time.
 
 > v3.6.0 — **Knowledge Graph First.** Every data source converges into the graph
 > through one unified ingestion pipeline (`latticeai/services/ingestion.py`), with

package/docs/kg-schema.md

@@ -1,9 +1,9 @@
 # Knowledge Graph Schema
 
-Current release: **9.8.0 — Honest Knowledge Pipeline**.
+Current release: **9.9.1 — Clean Foundations**.
 
 명세 출처: `lattice_ai_full_spec.pptx` 슬라이드 20·21·22
-구현: `kg_schema.py`
+구현: `lattice_brain/graph/schema.py`
 
 ---
 
@@ -179,8 +179,8 @@ provenance(source_type, source_uri, content_hash, captured_at, modified_at,
 
 ## 마이그레이션 (legacy → v2)
 
-기존 `knowledge_graph.py` 가 만든 `nodes` / `edges` 테이블은 자유 문자열 타입을
-사용해 왔다. `kg_schema.py` 는 매핑 표를 가지고 있어 정식 enum 으로 변환한다.
+기존 `lattice_brain/graph/store.py`(구 `knowledge_graph.py`) 가 만든 `nodes` / `edges` 테이블은 자유 문자열 타입을
+사용해 왔다. `lattice_brain/graph/schema.py` 는 매핑 표를 가지고 있어 정식 enum 으로 변환한다.
 
 | legacy 타입 (한글 동사) | → v2 `EdgeType` |
 |------------------------|------------------|
@@ -209,7 +209,7 @@ provenance(source_type, source_uri, content_hash, captured_at, modified_at,
 
 마이그레이션은 별도 CLI 없이 **서버 기동 시 자동으로** 일어난다:
 `knowledge_graph.KnowledgeGraphStore` 가 열릴 때 v2 스키마를 생성/치유하고
-(`kg_schema.KGStoreV2.init_schema` — 추가 컬럼은 `ALTER` 로 in-place 치유,
+(`lattice_brain.graph.schema.KGStoreV2.init_schema` — 추가 컬럼은 `ALTER` 로 in-place 치유,
 edges_v2 식별자 변경은 create→copy→swap 으로 재구축), legacy 데이터를
 v2 로 백필한다. 기존 `nodes` / `edges` 테이블은 삭제하지 않는다. v4 에서는
 `nodes_v2` / `edges_v2` 가 쓰기 마스터이며, legacy 테이블은 이전 import/API
@@ -243,7 +243,7 @@ v2 로 백필한다. 기존 `nodes` / `edges` 테이블은 삭제하지 않는
 read/write 는 `knowledge_graph.KnowledgeGraphStore` 가 담당한다:
 
 ```python
-from kg_schema import KGStoreV2, NodeType, EdgeType
+from lattice_brain.graph.schema import KGStoreV2, NodeType, EdgeType
 from knowledge_graph import KnowledgeGraphStore
 
 store = KnowledgeGraphStore(db_path, blob_dir)

package/docs/spec-vs-impl.md

@@ -1,6 +1,13 @@
 # Lattice AI — 명세(PPT) vs 구현(repo) 매핑
 
-`lattice_ai_full_spec.pptx` 의 사양과 현재 리포지토리 구현 사이의 정렬 상태를 한 장으로 정리한다.
+> **Status: historical** — 초기 PPT 명세 대비 갭을 정리한 스냅샷 문서다. 이후
+> 여러 갭이 해소되었다(예: `src-tauri/`의 Tauri 데스크탑 셸, SQLite 라이브
+> 스토어 + 임베딩/벡터 검색, 하이브리드 리트리벌 등). 현행 아키텍처의
+> 단일 진실은 [`../ARCHITECTURE.md`](../ARCHITECTURE.md)와
+> [`../FEATURE_STATUS.md`](../FEATURE_STATUS.md)이며, 아래 갭 서술은
+> 작성 시점 기준으로 보존한다.
+
+`lattice_ai_full_spec.pptx` 의 사양과 작성 시점 리포지토리 구현 사이의 정렬 상태를 한 장으로 정리한다.
 각 항목은 **목표(PPT) → 현재(repo) → 갭 → 보강 위치** 순으로 본다.
 
 ---

package/lattice_brain/__init__.py

@@ -26,7 +26,7 @@ from .storage import (
     storage_from_env,
 )
 
-__version__ = "9.8.0"
+__version__ = "9.9.1"
 
 __all__ = [
     "AgentRuntime",

package/lattice_brain/graph/schema.py

@@ -32,7 +32,7 @@ legacy 테이블에 대한 dual-write 프로젝션(raw SQL) + ``kgv2_*`` 재구
 사용 예
 -------
 ```python
-from kg_schema import KGStoreV2
+from lattice_brain.graph.schema import KGStoreV2
 
 store = KGStoreV2("/Users/me/.ltcai/kg_v2.db")
 store.init_schema()        # nodes_v2 / edges_v2 생성 + 컬럼 drift self-heal

package/lattice_brain/runtime/multi_agent.py

@@ -48,7 +48,7 @@ from .contracts import multi_agent_contract
 from ..utils import now_iso as _now
 
 
-MULTI_AGENT_VERSION = "9.8.0"
+MULTI_AGENT_VERSION = "9.9.1"
 
 AGENT_ROLES = ("researcher", "planner", "executor", "reviewer", "release")
 CORE_PIPELINE = ("planner", "executor", "reviewer")

package/latticeai/__init__.py

@@ -1,3 +1,3 @@
 """Lattice AI - modular server package."""
 
-__version__ = "9.8.0"
+__version__ = "9.9.1"

package/latticeai/api/review_queue.py

@@ -19,6 +19,7 @@ from typing import Any, Callable, Dict, List, Optional
 from fastapi import APIRouter, HTTPException, Request
 from pydantic import BaseModel, Field
 
+from latticeai.services.change_proposals import ProposalConflictError
 from latticeai.services.review_queue import InvalidReviewTransition, ReviewQueueService
 
 
@@ -151,6 +152,12 @@ def create_review_queue_router(
                     applied = change_proposals.approve_and_apply(
                         item_id, user_email=user, workspace_id=scope
                     )
+                except ProposalConflictError as exc:
+                    # The file drifted since staging (or the proposal was
+                    # already resolved): same 409-on-replay semantics as the
+                    # other illegal transitions, plus a rebase hint so the UI
+                    # can offer "re-stage against the current content".
+                    raise HTTPException(status_code=409, detail=exc.to_detail()) from exc
                 except (KeyError, FileNotFoundError) as exc:
                     raise HTTPException(status_code=404, detail=str(exc)) from exc
                 except ValueError as exc:

package/latticeai/core/agent.py

@@ -44,11 +44,17 @@ class AgentState(str, Enum):
     VERIFYING        = "VERIFYING"
     FAILED           = "FAILED"
     ROLLBACK         = "ROLLBACK"
+    # Terminal, non-success: the run ended but completion could not be
+    # verified (critic unavailable/unparseable, or a PASS with no execution
+    # evidence). Never presented as success — the user must check the result.
+    NEEDS_REVIEW     = "NEEDS_REVIEW"
     DONE             = "DONE"
 
 
 # Terminal states — the agent loop exits when reaching one of these
-AGENT_TERMINAL_STATES: FrozenSet[AgentState] = frozenset({AgentState.DONE, AgentState.FAILED})
+AGENT_TERMINAL_STATES: FrozenSet[AgentState] = frozenset(
+    {AgentState.DONE, AgentState.FAILED, AgentState.NEEDS_REVIEW}
+)
 
 
 class AgentRunContext:
@@ -574,11 +580,31 @@ class SingleAgentRuntime:
             })
 
     # ── VERIFY ───────────────────────────────────────────────────────
+    def _has_execution_evidence(self, ctx: AgentRunContext) -> bool:
+        """Deterministic evidence check: at least one executing step actually
+        produced a result (tool ran, or a governed change was staged as a
+        proposal). ``final``/parse-error/blocked steps carry no result and do
+        not count — a critic PASS over an evidence-free transcript must not
+        become DONE."""
+        for step in ctx.transcript:
+            if step.get("state") != AgentState.EXECUTING.value:
+                continue
+            if step.get("action") in (None, "final", "parse_error"):
+                continue
+            if isinstance(step.get("result"), dict):
+                return True
+        return False
+
     async def verify(
         self, ctx: AgentRunContext, req: Any, lang_hint: str, current_user: str,
         max_retry: int = 3, model_id: Optional[str] = None,
     ) -> None:
-        """VERIFYING: Critic role evaluates transcript → DONE / EXECUTING (retry) / ROLLBACK / FAILED."""
+        """VERIFYING: Critic role evaluates transcript → DONE / EXECUTING (retry) / ROLLBACK / NEEDS_REVIEW / FAILED.
+
+        Fail-closed: a critic whose output cannot be parsed (after one strict
+        repair retry) never fabricates a PASS — the run terminates as
+        NEEDS_REVIEW so the user is told to check the result themselves.
+        """
         d = self.deps
         context = (
             f"{d.critic_prompt}\n\n"
@@ -593,30 +619,91 @@ class SingleAgentRuntime:
             context=context, max_tokens=512, temperature=0.1,
         )
         ctx.trace.llm_call("verify", model=model_id)
+        verdict: Optional[Dict[str, Any]] = None
         try:
             verdict, verdict_repairs = extract_action_details(str(raw))
             ctx.trace.repair("verify", repairs=verdict_repairs)
         except ValueError as exc:
+            # One strict repair retry — re-ask the critic for the exact wire
+            # format instead of fabricating a verdict.
             ctx.trace.parse_error("verify", error=str(exc), recovered=True)
-            verdict = {"action": "verdict", "verdict": "PASS", "next_state": "DONE",
-                       "reason": "Critic parse failed — assuming pass.", "corrections": [], "confidence": 0.7}
+            strict_context = (
+                f"{context}\n\n"
+                "Your previous verdict was not parseable JSON. Reply with EXACTLY one "
+                'JSON object like {"action": "verdict", "verdict": "PASS", '
+                '"next_state": "DONE", "reason": "...", "corrections": []} '
+                "and nothing else. verdict must be PASS or FAIL; next_state must be "
+                "one of DONE, EXECUTING, ROLLBACK, FAILED."
+            )
+            raw = await d.generate_as(
+                model_id,
+                message="Return your verdict as one strict JSON object.",
+                context=strict_context, max_tokens=512, temperature=0.0,
+            )
+            ctx.trace.llm_call("verify", model=model_id)
+            try:
+                verdict, verdict_repairs = extract_action_details(str(raw))
+                ctx.trace.repair("verify", repairs=verdict_repairs)
+            except ValueError as retry_exc:
+                ctx.trace.parse_error("verify", error=str(retry_exc), recovered=False)
+                verdict = None
+
+        has_evidence = self._has_execution_evidence(ctx)
+
+        if verdict is None:
+            # Verifier unavailable — fail closed, never DONE.
+            ctx.transcript.append({
+                "state": AgentState.VERIFYING.value,
+                "verdict": "UNAVAILABLE",
+                "reason": "critic output unparseable after strict retry",
+                "verifier_available": False,
+                "verdict_valid": False,
+                "evidence": has_evidence,
+            })
+            ctx.trace.decision(
+                "verify", decision="verification_unavailable",
+                verifier_available=False, verdict_valid=False, evidence=has_evidence,
+            )
+            ctx.final_message = (
+                "검증을 완료하지 못했습니다 — 검증 모델의 응답을 해석할 수 없었습니다. "
+                "실행 결과를 직접 확인해 주시고, 필요하면 다시 시도해 주세요."
+            )
+            ctx.state = AgentState.NEEDS_REVIEW
+            return
 
         ctx.corrections = verdict.get("corrections", [])
         # Normalize legacy verdict next_state strings to current AgentState names
-        raw_next = verdict.get("next_state", "DONE")
+        raw_next = verdict.get("next_state", "")
         next_s = {"COMPLETE": "DONE", "RETRY": "EXECUTING"}.get(raw_next, raw_next)
 
         ctx.transcript.append({
             "state": AgentState.VERIFYING.value,
-            "verdict":     verdict.get("verdict", "PASS"),
+            "verdict":     verdict.get("verdict", ""),
             "reason":      verdict.get("reason", ""),
             "corrections": ctx.corrections,
             "confidence":  verdict.get("confidence", 0.9),
             "next_state":  next_s,
+            "verifier_available": True,
+            "verdict_valid": True,
+            "evidence": has_evidence,
         })
 
-        ctx.trace.decision("verify", decision=str(verdict.get("verdict", "PASS")), next_state=next_s)
-        if verdict.get("verdict") == "PASS" or next_s == "DONE":
+        ctx.trace.decision(
+            "verify", decision=str(verdict.get("verdict", "")), next_state=next_s,
+            verifier_available=True, verdict_valid=True, evidence=has_evidence,
+        )
+        if verdict.get("verdict") == "PASS":
+            # DONE requires both: a validly parsed PASS verdict AND
+            # deterministic execution evidence in the transcript. A PASS over
+            # an evidence-free run is not a completion.
+            if not has_evidence:
+                ctx.trace.decision("verify", decision="needs_review_no_evidence")
+                ctx.final_message = (
+                    "검증자는 통과를 보고했지만 실제 실행 근거(도구 실행 기록)가 없어 "
+                    "완료로 처리하지 않았습니다. 결과를 직접 확인해 주세요."
+                )
+                ctx.state = AgentState.NEEDS_REVIEW
+                return
             if not ctx.final_message:
                 ctx.final_message = verdict.get("reason", "작업이 완료되었습니다.")
             ctx.state = AgentState.DONE
@@ -635,6 +722,16 @@ class SingleAgentRuntime:
                     "corrections": ctx.corrections,
                 })
                 ctx.state = AgentState.EXECUTING
+        elif next_s == "DONE":
+            # Contradictory verdict: the critic asked for DONE without a PASS.
+            # The loose "or next_state == DONE" success path is gone — this is
+            # a non-success that the user must review.
+            ctx.trace.decision("verify", decision="needs_review_inconsistent_verdict")
+            ctx.final_message = (
+                "검증 결과가 일관되지 않아 완료로 처리하지 않았습니다. "
+                "실행 결과를 직접 확인해 주세요."
+            )
+            ctx.state = AgentState.NEEDS_REVIEW
         else:
             ctx.final_message = verdict.get("reason", "검증자가 인식되지 않은 다음 상태를 반환했습니다.")
             ctx.state = AgentState.FAILED