ltcai 9.7.0 → 9.9.0

package/docs/CHANGELOG.md

@@ -4,6 +4,78 @@ The top entry is either the current unreleased main-branch work or the current
 release line. Older entries are historical and may describe behavior as it
 existed at that release.
 
+## [9.9.0] - 2026-07-21
+
+### Fixed
+- Change proposals record the target's original content hash and existence;
+  approval re-hashes the disk and rejects a modified/deleted/created target
+  with a 409 conflict instead of overwriting newer content. Applies are atomic
+  (`os.replace`) and serialized so duplicate/concurrent approvals apply once.
+- The agent verifier no longer fabricates a PASS on unparseable critic output:
+  one strict repair retry, then the new terminal `NEEDS_REVIEW` state. `DONE`
+  now requires a valid PASS and deterministic execution evidence; the loose
+  `next_state == DONE` success path is removed.
+- Device analysis no longer fabricates a `supported: true` model card on probe
+  failure; the recommendation screen models `loading | ready | unavailable`
+  and offers retry / continue-without-a-model.
+
+### Added
+- `MUTATING_TOOL_INVENTORY` single-source governance classification for every
+  side-effecting tool, a fail-closed CI coverage gate, and dispatch-level
+  blocking (409) of existing-content overwrites that cannot be staged as a
+  reviewable proposal (`create_docx/xlsx/pptx/pdf`, `local_write`).
+- Agent-eval result classification (`correct_completion` / `safe_termination`
+  / `needs_review` / `failed`) and fail-closed verifier scenarios (20 total).
+- CI: `dependency-audit.yml` (pip-audit + npm audit + CycloneDX SBOM) and
+  scheduled `postgres-integration.yml`; all GitHub Actions SHA-pinned; a
+  frontend bundle-budget gate (150 KiB gzip).
+- `docs/SECURITY_AUDIT.md`, `docs/BENCHMARKS.md` + `scripts/bench_models.py`,
+  `docs/USABILITY_AUDIT.md`, `docs/CI_AND_RELEASE_GATES.md`, and a
+  documentation status/link gate (`scripts/check_doc_status.mjs`).
+
+### Changed
+- Initial JS bundle reduced ~22% (180.3 → 141.6 KiB gzip) via lazy-loaded
+  onboarding, Brain home, and command palette.
+- `ARCHITECTURE.md` verified against the real module layout and corrected;
+  stale 9.6-era operational/feature/development docs updated and classified.
+
+## [9.8.0] - 2026-07-20
+
+### Added
+- Added `extraction_quality` (score/level/reasons) and low-quality `warnings`
+  to every ingest result, with upstream extractor confidence taking
+  precedence; the proactive `gate_ingest_candidate()` now records an
+  observe-only `quality_gate` verdict on non-chat ingests.
+- Added background ingestion job progress (`total`/`processed`/`failed`,
+  capped per-item errors) with resume-from-remaining support, plus
+  `GET /api/ingestion/jobs`, `GET /api/ingestion/jobs/{id}`,
+  `POST /api/ingestion/jobs/{id}/resume`, and approval-gated
+  `POST /api/ingestion/folder`.
+- Added `context_quality` (mode/nodes/limited/reason) to chat responses
+  (non-stream top-level and final SSE trailer) with a localized
+  limited-context note in the assistant bubble.
+- Added `GET /api/brain/vector-freshness` and a pending-indexing chip in the
+  Brain views; `vector_freshness()` never raises and degrades to
+  `unavailable` with a reason.
+- Added four agent-eval scenarios (ingestion chain, concept extraction,
+  RAG-grounded answer with a negative grounding test, automation
+  proposal-first), growing the CI gate to 16 scenarios with
+  `expect_final_contains` grounding assertions.
+- Added deterministic `confidence`, `confidence_factors`, duplicate
+  suppression, installed-recipe detection, and a low-quality floor to
+  automation suggestions, with a `quality` reporting block.
+- Added a frontend ingestion jobs panel (progress bar, failed count, resume)
+  and extraction-quality warnings in the ingestion panels, all with ko/en
+  i18n parity.
+
+### Changed
+- Rebuilt README media-first: hero walkthrough GIF, screenshot grid, compact
+  release-history table, and roughly 60% less prose.
+- `context_for_query()` gains an opt-in metadata path
+  (`context_for_query_with_meta()`); the default output is byte-identical.
+- Background ingestion job initial status is now `queued` (was internal
+  `pending`).
+
 ## [9.7.0] - 2026-07-20
 
 ### Added

package/docs/CI_AND_RELEASE_GATES.md

@@ -0,0 +1,106 @@
+# CI & Release Gates
+
+> Status: reference 2026-07-21
+
+Reference for the GitHub Actions workflows that guard `main` and releases, the
+supply-chain hardening applied to them, and the recommended branch-protection
+configuration. Companion to [SECURITY_AUDIT.md](SECURITY_AUDIT.md) and
+[BENCHMARKS.md](BENCHMARKS.md).
+
+## Workflows
+
+| Workflow | File | Triggers | Purpose |
+|----------|------|----------|---------|
+| CI | `.github/workflows/ci.yml` | push/PR to `main` | Lint, typecheck, unit + integration tests, brain/agent eval gates, build + wheel smoke |
+| Release | `.github/workflows/release.yml` | tags `v*` / `[0-9]*` | Build & validate all artifacts (no publish) |
+| Visual Smoke | `.github/workflows/visual.yml` | push/PR, nightly cron, dispatch | Playwright visual smoke |
+| **Dependency Audit** | `.github/workflows/dependency-audit.yml` | push/PR, weekly cron, dispatch | pip-audit + npm audit + CycloneDX SBOMs |
+| **Postgres Integration** | `.github/workflows/postgres-integration.yml` | weekly cron, dispatch | Live SQLite→Postgres/pgvector migration test |
+
+The last two were added for the P2 deployment-trust / supply-chain workstream.
+
+## Supply-chain hardening: pinned actions
+
+Every third-party `uses:` in every workflow is pinned to an **immutable commit
+SHA**, with the human-readable version in a trailing comment. A moving tag
+(`@v4`) can be repointed by the action owner; a SHA cannot. SHAs were resolved
+from the authoritative upstream refs via `git ls-remote --tags` on 2026-07-21.
+
+| Action | Tag | Pinned commit SHA |
+|--------|-----|-------------------|
+| actions/checkout | v4.4.0 | `11d5960a326750d5838078e36cf38b85af677262` |
+| actions/checkout | v5.1.0 | `fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09` |
+| actions/setup-python | v5.6.0 | `a26af69be951a213d495a4c3e4e4022e16d87065` |
+| actions/setup-python | v6.3.0 | `ece7cb06caefa5fff74198d8649806c4678c61a1` |
+| actions/setup-node | v5.0.0 | `a0853c24544627f65ddf259abe73b1d18a591444` |
+| actions/upload-artifact | v4.6.2 | `ea165f8d65b6e75b540449e92b4886f43607fa02` |
+
+Pinning coverage: **100% of current `uses:` entries** across `ci.yml`,
+`release.yml`, `visual.yml`, `dependency-audit.yml`, and
+`postgres-integration.yml`. All are first-party `actions/*`. If a third-party
+action is added later, resolve and pin its SHA the same way before merge.
+
+## Dependency-audit gate posture (conservative)
+
+The audit workflow is intentionally **non-blocking on day-to-day PRs** and
+**strict on the scheduled/dispatch run**:
+
+- `push` / `pull_request`: `pip-audit` and `npm audit` run with
+  `continue-on-error` keyed on the event name, so a newly-disclosed CVE in a
+  transitive dependency never reddens an unrelated PR. Findings still appear in
+  the job summary and uploaded report artifacts.
+- `schedule` (weekly) / `workflow_dispatch`: the same steps run **strict** —
+  `pip-audit --strict` fails on any known vuln; `npm audit --audit-level=high`
+  fails on high/critical. This is the loud channel for triage.
+
+CycloneDX SBOMs (`sbom-python.json`, `sbom-npm.json`) are produced every run and
+uploaded as artifacts. Regenerate locally with `scripts/generate_sbom.py`.
+
+**To promote to a required blocking PR check:** remove the `continue-on-error`
+expressions in `dependency-audit.yml` and add `python-audit` / `npm-audit` to
+the required-checks list below.
+
+## Postgres integration gate
+
+`postgres-integration.yml` runs the migration-integrity suite
+(`tests/integration/test_v42_postgres_migration_live.py`) that is skipped
+everywhere else. The suite is gated by `LTCAI_LIVE_POSTGRES_DOCKER_CONSENT=1`;
+the workflow sets that variable, and the test itself starts and tears down a
+`pgvector/pgvector:pg16` container via `docker compose` (preinstalled on
+GitHub-hosted `ubuntu-latest`). It is deliberately kept off the PR path (slow,
+image pull, needs Docker) and runs weekly + on demand.
+
+## Recommended branch protection for `main`
+
+Required status checks (blocking):
+
+- `CI / Test (Python 3.11)`
+- `CI / Test (Python 3.12)`
+- `CI / Integration smoke test`
+- `CI / Build package`
+- `Visual Smoke / Playwright visual smoke`
+
+Advisory / non-blocking today (promote when the team is ready):
+
+- `Dependency Audit / Python dependency audit (pip-audit)`
+- `Dependency Audit / npm dependency audit`
+
+Additional recommended settings: require PRs before merge, require branches to
+be up to date, require linear history, and dismiss stale approvals on new
+commits.
+
+## Release gate (publication safety)
+
+`release.yml` builds and validates artifacts only — it never publishes. Package
+publication (PyPI / npm / VS Code Marketplace / Open VSX) is a manual step
+(`npm run publish:*`) using **exact version filenames**, never a `dist/*` glob,
+so pushing a tag can never publish by accident. See
+[../RELEASE.md](../RELEASE.md) for the full procedure.
+
+## Limitations (honest)
+
+- Branch-protection rules are repository settings and cannot be committed from a
+  workflow; the list above is the recommended configuration to apply in GitHub
+  settings, not an enforced artifact.
+- The audit gate depends on upstream advisory databases (OSV, npm registry);
+  absence of findings means "nothing known", not "provably safe".

package/docs/COMMUNITY_AND_PLUGINS.md

@@ -1,6 +1,6 @@
 # Community And Plugins
 
-Current release: **9.7.0 — Proactive Hybrid Brain**.
+Current release: **9.9.0 — Fail-Closed Trust**.
 
 LatticeAI defines the path from a strong local-first framework (8.4.0
 action-aware baseline, 8.5.0 registry+DI hardening, 8.6.0 capture/navigation

package/docs/DEVELOPMENT.md

@@ -1,10 +1,13 @@
 # Lattice AI Development
 
-Current release: **9.7.0 — Proactive Hybrid Brain**.
+> **Status: canonical** — current contributor guidance, kept in sync with the
+> current release.
+
+Current release: **9.9.0 — Fail-Closed Trust**.
 
 This document is for contributors working on the local-first Digital Brain
 codebase. Product positioning and quick start stay in `README.md`; release
-history is intentionally limited to 8.0.0-9.6.0 in `docs/CHANGELOG.md` and
+history is intentionally limited to 8.0.0-9.9.0 in `docs/CHANGELOG.md` and
 `RELEASE.md`.
 
 ## Product Contract
@@ -153,10 +156,10 @@ For user-facing, API, runtime, release, or packaging changes, check:
 Release/publish examples must use exact target-version filenames. Do not
 document wildcard artifact upload commands.
 
-For 9.6.0 release work, exact artifacts are:
+For 9.9.0 release work, exact artifacts are:
 
-- `dist/ltcai-9.6.0-py3-none-any.whl`
-- `dist/ltcai-9.6.0.tar.gz`
-- `ltcai-9.6.0.tgz`
-- `dist/ltcai-9.6.0.vsix`
-- `src-tauri/target/release/bundle/dmg/Lattice AI_9.6.0_aarch64.dmg`
+- `dist/ltcai-9.9.0-py3-none-any.whl`
+- `dist/ltcai-9.9.0.tar.gz`
+- `ltcai-9.9.0.tgz`
+- `dist/ltcai-9.9.0.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_9.9.0_aarch64.dmg`

package/docs/ONBOARDING.md

@@ -1,6 +1,6 @@
 # Lattice AI Onboarding
 
-Current release: **9.7.0 — Proactive Hybrid Brain**.
+Current release: **9.9.0 — Fail-Closed Trust**.
 
 The first-run goal is a five-minute path from "I opened the app" to "my Brain
 has a source, a question, and proof." This page is the product contract behind

package/docs/OPERATIONS.md

@@ -1,13 +1,18 @@
-# Lattice AI — Operations Guide (v9.6.0)
+# Lattice AI — Operations Guide (v9.9.0)
+
+> **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.7.0 — Proactive Hybrid Brain**.
+Current release: **9.9.0 — Fail-Closed Trust**.
 
 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.7.0 — Proactive Hybrid Brain**.
+Current release: **9.9.0 — Fail-Closed Trust**.
 
 **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,6 +1,6 @@
 # Knowledge Graph Schema
 
-Current release: **9.7.0 — Proactive Hybrid Brain**.
+Current release: **9.9.0 — Fail-Closed Trust**.
 
 명세 출처: `lattice_ai_full_spec.pptx` 슬라이드 20·21·22
 구현: `kg_schema.py`

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.7.0"
+__version__ = "9.9.0"
 
 __all__ = [
     "AgentRuntime",