ltcai 9.8.0 → 9.9.1

package/README.md

@@ -11,7 +11,7 @@
 [![CI Status](https://github.com/TaeSooPark-PTS/LatticeAI/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/TaeSooPark-PTS/LatticeAI/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
-![v9.8.0 Living Brain walkthrough](output/release/v9.8.0/gifs/v9.8.0-living-brain-walkthrough.gif)
+![v9.9.1 Living Brain walkthrough](output/release/v9.9.1/gifs/v9.9.1-living-brain-walkthrough.gif)
 
 Chat, files, folders, notes, and web pages all flow into one durable knowledge
 graph on your computer. Any model — local MLX or cloud — can speak with that
@@ -24,9 +24,9 @@ memory. Nothing leaves your machine without explicit consent.
 
 | | |
 | --- | --- |
-| **Chat with a Brain that remembers** — every conversation grows durable, source-linked memory ![Brain Chat](output/release/v9.8.0/screenshots/04-brain-chat-home.png) | **See how knowledge connects** — a real relationship graph, not a file list ![Memory Graph](output/release/v9.8.0/screenshots/05-memory-graph.png) |
-| **Capture anything** — files, whole folders, notes, screenshots, web pages ![Capture](output/release/v9.8.0/screenshots/06-capture.png) | **Automate with review** — agent changes become proposals you approve first ![Review Center](output/release/v9.8.0/screenshots/12-review-center.png) |
-| **Pick a model in one click** — recommended local models for your hardware ![Recommended Models](output/release/v9.8.0/screenshots/02-recommended-models.png) | **Stay in control** — audit, roles, retention in a separate admin surface ![Admin Console](output/release/v9.8.0/screenshots/10-admin-console.png) |
+| **Chat with a Brain that remembers** — every conversation grows durable, source-linked memory ![Brain Chat](output/release/v9.9.1/screenshots/04-brain-chat-home.png) | **See how knowledge connects** — a real relationship graph, not a file list ![Memory Graph](output/release/v9.9.1/screenshots/05-memory-graph.png) |
+| **Capture anything** — files, whole folders, notes, screenshots, web pages ![Capture](output/release/v9.9.1/screenshots/06-capture.png) | **Automate with review** — agent changes become proposals you approve first ![Review Center](output/release/v9.9.1/screenshots/12-review-center.png) |
+| **Pick a model in one click** — recommended local models for your hardware ![Recommended Models](output/release/v9.9.1/screenshots/02-recommended-models.png) | **Stay in control** — audit, roles, retention in a separate admin surface ![Admin Console](output/release/v9.9.1/screenshots/10-admin-console.png) |
 
 ## Why Lattice AI
 
@@ -57,36 +57,49 @@ First-run flow — wake the Brain, pick the owner, load a recommended model:
 
 | | | |
 | --- | --- | --- |
-| ![Login](output/release/v9.8.0/screenshots/01-login.png) | ![Model install](output/release/v9.8.0/screenshots/03-install-load-progress.png) | ![Model library](output/release/v9.8.0/screenshots/07-model-library.png) |
+| ![Login](output/release/v9.9.1/screenshots/01-login.png) | ![Model install](output/release/v9.9.1/screenshots/03-install-load-progress.png) | ![Model library](output/release/v9.9.1/screenshots/07-model-library.png) |
 
 Screenshot index and capture notes:
-[output/release/v9.8.0/SCREENSHOT_INDEX.md](output/release/v9.8.0/SCREENSHOT_INDEX.md)
+[output/release/v9.9.1/SCREENSHOT_INDEX.md](output/release/v9.9.1/SCREENSHOT_INDEX.md)
 
 ## Current Release
 
-The current release is **9.8.0 — Honest Knowledge Pipeline**:
-
-- Every ingest (file, folder, web) now reports an extraction-quality score and
-  warns on low-quality captures before they pollute the Brain.
-- Background folder ingestion is robust: per-item errors don't kill the job,
-  progress (processed/total) is visible, and interrupted jobs resume — with a
-  jobs API (`/api/ingestion/jobs`) and UI progress.
-- The Brain signals honestly: chat answers carry a `context_quality` marker
-  when graph context is limited, and `/api/brain/vector-freshness` plus a UI
-  banner show when knowledge is still waiting for vector indexing.
-- The agent evaluation gate grew to 16 deterministic scenarios, adding
-  ingestion, concept-extraction, RAG-grounded answering, and automation
-  proposal paths; automation suggestions gain confidence scoring and dedup.
+The current release is **9.9.1 — Clean Foundations**:
+
+- **A clean core.** The historical repo-root compatibility shims are gone
+  (only `server.py` remains for `uvicorn server:app`); packaging ships exactly
+  the `latticeai.*` / `lattice_brain.*` packages, and a legacy debt gate in
+  `npm run lint` plus a dedicated test suite keep the root clean for good.
+- **Your first five minutes matter.** A guided "First 5 minutes" card on the
+  empty Brain home walks a new user through asking a first question, adding a
+  first file or note, and seeing what the Brain learned — wired to real
+  features, with progress that persists and a briefing that loads immediately.
+- **Proactive intelligence you can actually see.** Today's briefing now lives
+  on the Brain home instead of a double-collapsed drawer, and Cmd+K opens with
+  proactive quick actions (open briefing, review pending items, ask the Brain)
+  before you type a single letter.
+- **Review Center at product quality.** Proposal cards translate risk and
+  change class into human language, frame diffs with file targets and honest
+  truncation counts, tuck raw IDs into a "Technical details" disclosure, and
+  every approve/reject failure shows a friendly message first.
+- **Errors that speak your language.** The API error pipeline is localized
+  (ko/en): timeouts, unreachable-service, and backend failures produce plain,
+  helpful copy instead of raw `statusText` or English literals, across chat,
+  admin, care, and intelligence panels.
+- **Scenario-first tests, smaller evidence footprint.** 37 version-named test
+  files were renamed to behavior-named suites, and `output/release/` now keeps
+  only the newest three evidence sets (~70MB reclaimed) via an automated
+  retention policy.
 
 Release notes: [RELEASE.md](RELEASE.md) · Full history: [docs/CHANGELOG.md](docs/CHANGELOG.md)
 
-Expected artifacts for 9.8.0 release must use exact filenames:
+Expected artifacts for 9.9.1 release must use exact filenames:
 
-- `dist/ltcai-9.8.0-py3-none-any.whl`
-- `dist/ltcai-9.8.0.tar.gz`
-- `ltcai-9.8.0.tgz`
-- `dist/ltcai-9.8.0.vsix`
-- `src-tauri/target/release/bundle/dmg/Lattice AI_9.8.0_aarch64.dmg`
+- `dist/ltcai-9.9.1-py3-none-any.whl`
+- `dist/ltcai-9.9.1.tar.gz`
+- `ltcai-9.9.1.tgz`
+- `dist/ltcai-9.9.1.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_9.9.1_aarch64.dmg`
 
 Do not use wildcard artifact uploads. Package registry publishing remains owner-run.
 
@@ -106,16 +119,20 @@ See [ARCHITECTURE.md](ARCHITECTURE.md) for details and
 
 - External package registries are owner-published and can lag behind GitHub.
 - PostgreSQL/pgvector is optional scale/migration tooling. SQLite remains the
-  live local Brain store in 9.8.0.
+  live local Brain store in 9.9.1.
 - Docker, model downloads, cloud model calls, Telegram, Brain Network, and
   update checks require explicit user action.
-- Conversation does not fabricate answers when no model is loaded; LLM-free
-  simulation is labeled as such.
+- Conversation does not fabricate answers when no model is loaded. Agent and
+  workflow simulation without a loaded LLM is deterministic and LLM-free (it
+  does not call a model) — labeled as such, never presented as autonomous
+  model success.
 
 ## Release History
 
 | Version | Theme |
 | --- | --- |
+| 9.9.1 | Clean Foundations |
+| 9.9.0 | Fail-Closed Trust |
 | 9.8.0 | Honest Knowledge Pipeline |
 | 9.7.0 | Proactive Hybrid Brain |
 | 9.6.0 | Trusted Agent Loop |

package/bin/ltcai.js

@@ -90,7 +90,7 @@ function run(index) {
     process.exit(1);
   }
 
-  const child = spawn(python, [path.join(root, "ltcai_cli.py"), ...process.argv.slice(2)], {
+  const child = spawn(python, ["-m", "latticeai.cli.entrypoint", ...process.argv.slice(2)], {
     cwd: root,
     stdio: "inherit",
   });

package/desktop/electron/main.cjs

@@ -20,7 +20,7 @@ ipcMain.handle("lattice:select-folder", async (event) => {
 
 function startBackend() {
   if (process.env.LATTICEAI_DESKTOP_NO_BACKEND) return;
-  const command = process.env.LATTICEAI_DESKTOP_BACKEND_CMD || "python3 ltcai_cli.py --host 127.0.0.1 --port 4825";
+  const command = process.env.LATTICEAI_DESKTOP_BACKEND_CMD || "python3 -m latticeai.cli.entrypoint --host 127.0.0.1 --port 4825";
   const [bin, ...args] = command.split(/\s+/).filter(Boolean);
   if (!bin) return;
   backend = spawn(bin, args, {

package/docs/BENCHMARKS.md

@@ -0,0 +1,107 @@
+# Model Robustness Benchmarks
+
+> Status: reference 2026-07-21
+
+Methodology and results for `scripts/bench_models.py`, a harness that measures
+how well the agent loop turns model output into executable actions across model
+quality tiers. Companion to [CI & Release Gates](CI_AND_RELEASE_GATES.md).
+
+## What is measured
+
+The product claim is that the Brain stays durable "across any AI model": weaker
+models emit sloppier output, but the loop repairs it and still completes the
+task. The harness turns that into three numbers per tier:
+
+- **success_rate** — fraction of model outputs that become a valid agent action
+  (the task can proceed).
+- **repair_rate** — of the successful parses, the fraction that succeeded *only
+  because* the loop's tolerant parser had to repair the output. High = "this
+  tier leans hard on the loop's robustness".
+- **latency_ms** — see the honesty note below.
+
+Every output is fed through the **real** parser the production loop uses:
+`latticeai.core.agent.extract_action_details` (called from `agent.py` in the
+plan/execute/verify phases). The harness does not reimplement parsing — it
+measures the shipping code. Its known repair tolerances are: `think_strip`
+(strip `<think>` blocks), `fence` (unwrap ```` ```json ````), `slice` (extract
+the `{...}` span from prose), `trailing_comma`, and `python_literal`
+(`ast.literal_eval` of a single-quoted dict).
+
+An `agent-loop` reference row additionally runs the real
+`latticeai.core.agent_eval.run_agent_eval` state machine over its 20 scripted
+scenarios and reports its success and recovery rates.
+
+## Honesty note on latency
+
+In **scripted** mode, `latency_ms` is the **parse+repair cost only**
+(microseconds). It is **not** model inference time and must not be read as such.
+True generation latency is only meaningful in **live** mode against a real
+endpoint.
+
+## Modes
+
+1. **scripted** (default; no model, no network): a curated corpus of
+   model-realistic outputs per tier. Deterministic; proves the harness works and
+   exposes the loop's repair boundary. Some weak-tier entries are *intentionally
+   broken* past the repair boundary so `success_rate < 1.0` is a real finding,
+   not a rigged demo. A self-check asserts every corpus entry's expected
+   parse/fail outcome matches reality (0 mismatches = healthy).
+2. **live** (opt-in): sends a fixed prompt set to an OpenAI-compatible local
+   endpoint (LM Studio / llama.cpp / vLLM), runs the real completions through
+   the same parser, and reports **true** generation latency. Falls back to a
+   clear "SKIPPED" line if the endpoint is unreachable.
+
+## Running
+
+```bash
+# Scripted matrix (always works):
+.venv/bin/python scripts/bench_models.py
+
+# With machine-readable output:
+.venv/bin/python scripts/bench_models.py --json bench.json
+
+# Against a real local model (OpenAI-compatible endpoint):
+.venv/bin/python scripts/bench_models.py \
+    --live-endpoint http://127.0.0.1:1234/v1 --model my-local-model
+```
+
+Exit code is non-zero only if the harness self-check finds an inconsistency (a
+real bug); a low score on a weak tier is a finding, not a failure.
+
+## Reference results (scripted, 2026-07-21)
+
+Captured on the maintainer's machine; latency is parse-only.
+
+| Tier | success_rate | repair_rate | n | repairs exercised |
+|------|-------------:|------------:|--:|-------------------|
+| frontier (clean JSON) | 1.00 | 0.00 | 6 | — |
+| mid-local (fenced/prose/commas) | 1.00 | 1.00 | 6 | fence×3, slice×1, trailing_comma×2 |
+| weak-local (think/py-literal/broken) | 0.625 | 1.00 | 8 | think_strip×2, python_literal×2, fence×1, trailing_comma×1 |
+
+Agent-loop reference (real state machine): **success_rate 1.00**, **recovery_rate
+0.70** over 20 scenarios. Harness self-check: **0 mismatches**.
+
+Reading the matrix: the mid tier is fully recoverable — every output needed a
+repair, and all succeeded, which is exactly the "durable across models" claim in
+action. The weak tier's 0.625 is the honest boundary: the 3 genuinely broken
+outputs (pure prose, missing `action` field, truncated braces) cannot and should
+not parse.
+
+## Measurable vs not-measurable (honest scope)
+
+**This harness can measure:**
+- Whether a given model's raw output survives the loop's parser (success_rate).
+- How much the loop's repair layer is doing the work (repair_rate + which
+  tolerances fire).
+- Real end-to-end generation latency in `live` mode.
+- End-to-end loop completion over the scripted scenario suite.
+
+**This harness does NOT measure:**
+- Task *correctness* / answer quality — only that an action is well-formed and
+  executable, not that it is the *right* action.
+- Multi-turn reasoning quality or tool-selection accuracy beyond the scripted
+  scenarios.
+- Throughput/latency under concurrency or on other hardware.
+- Any cloud model (no keys are used; live mode targets local endpoints only).
+- A representative sample of "all models" — scripted tiers are archetypes, not a
+  statistical population. For real numbers on a specific model, use `live` mode.

package/docs/CHANGELOG.md

@@ -4,6 +4,88 @@ 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.1] - 2026-07-21
+
+### Removed
+- All repo-root compatibility shims except `server.py`: `ltcai_cli.py`,
+  `auto_setup.py`, `setup_wizard.py`, `mcp_registry.py`, `kg_schema.py`,
+  `knowledge_graph.py`, `knowledge_graph_api.py`, `local_knowledge_api.py`,
+  `llm_router.py`, `p_reinforce.py`, `telegram_bot.py`, and the root `tools/`
+  package (12 of 13 tracked shims, 92%). Canonical imports are the
+  `latticeai.*` / `lattice_brain.*` module paths; the console script and
+  `bin/ltcai.js` now target `latticeai.cli.entrypoint` directly.
+- Stale release evidence: `output/release/` now keeps only the newest three
+  versioned evidence directories (automated retention policy).
+
+### Added
+- Legacy debt gate: `scripts/check_legacy_debt.mjs` in `npm run lint` plus a
+  rewritten `tests/unit/test_legacy_root_shims.py` fail if a root module
+  reappears or any source tree imports a removed shim.
+- `scripts/prune_release_evidence.mjs` retention policy (newest 3, override
+  with `LTCAI_RELEASE_EVIDENCE_KEEP`), wired into `npm run release:evidence`.
+- First-run "First 5 minutes" guided card on the empty Brain home: ask a first
+  question, add a first file/note, see what the Brain learned — real feature
+  wiring, persistent progress, dismissible.
+- Daily briefing on the Brain home (immediate fetch, friendly empty state) and
+  proactive quick actions on Cmd+K cold open (open briefing, review pending,
+  ask the Brain) with live counts.
+- Localized API error pipeline: timeout/unreachable/status failures map to
+  friendly ko/en copy instead of raw `statusText` or English literals.
+- `scripts/check_current_release_docs.mjs` now verifies the ARCHITECTURE.md
+  Release Artifact Map names current-version artifacts exactly.
+
+### Changed
+- Review Center at product quality: translated status/source/risk/change-class
+  labels, framed diffs (file target, +/- coloring, honest truncation count),
+  raw IDs relegated to a collapsed "Technical details" disclosure, structured
+  success/failure feedback, and a distinct error state with retry for the
+  pending-proposals panel.
+- Intelligence/care/admin/markdown panels show friendly i18n error copy first;
+  raw backend detail is demoted to secondary text.
+- 37 version-named test files (`test_v3_*`, `test_v42_*` … `test_t9_*`,
+  `test_kg_v2/v4_*`) renamed to scenario-named suites; versioned test
+  function names cleaned up. Coverage is unchanged (1284 unit tests).
+- Packaging: `pyproject.toml` ships a single root module (`server`);
+  `package.json` files list and `MANIFEST.in` no longer ship shim files.
+- Docs: `docs/LEGACY_COMPATIBILITY.md` rewritten for the post-shim layout;
+  `docs/kg-schema.md` points at `lattice_brain/graph/schema.py`; ARCHITECTURE
+  artifact map and 9.8.0-era references brought current.
+
+## [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

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_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.8.0 — Honest Knowledge Pipeline**.
+Current release: **9.9.1 — Clean Foundations**.
 
 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.8.0 — Honest Knowledge Pipeline**.
+> **Status: canonical** — current contributor guidance, kept in sync with the
+> current release.
+
+Current release: **9.9.1 — Clean Foundations**.
 
 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/LEGACY_COMPATIBILITY.md

@@ -1,18 +1,18 @@
 # Legacy Compatibility Map
 
-Current target: **9.6.0 — Trusted Agent Loop**.
+Current target: **9.9.1 — Legacy debt paydown**.
 
-Lattice AI is moving toward a smaller, modular architecture centered on
-`lattice_brain`, `latticeai.services`, `latticeai.api`, and `latticeai.runtime`.
-Some root-level modules remain packaged for compatibility with older imports,
-CLI entrypoints, or extension workflows. Their presence does not define the
-current architecture.
+Lattice AI is centered on `lattice_brain`, `latticeai.services`, `latticeai.api`,
+and `latticeai.runtime`. 9.9.1 completed the root-shim compatibility window:
+every repo-root import shim except `server.py` was physically deleted, and a
+legacy debt gate keeps the root clean.
 
 The managed inventory lives in `latticeai.core.legacy_compatibility` and
 groups shims by layer:
 
-- `root`: historical repo-root imports such as `knowledge_graph.py` — **kept**
-  (external entrypoints: `uvicorn server:app`, installed CLI, old scripts).
+- `root`: historical repo-root imports such as `knowledge_graph.py` —
+  **removed in 9.9.1** except `server.py` (external entrypoints:
+  `uvicorn server:app`, Docker CMD, launch scripts).
 - `brain-flat`: pre-graph-package imports such as `lattice_brain.store` —
   **removed in 8.8.0** (internal-only).
 - `deprecated-namespace`: older `latticeai.brain.*` package imports —
@@ -24,11 +24,44 @@ Removed layers stay listed in `legacy_compatibility.REMOVED_SHIMS` and in the
 `legacy_shim_report()` payload (`removed`, `lingering`), so tooling can tell
 "removed on purpose" apart from "missing by accident".
 
+## Legacy Debt Gate
+
+Two gates keep the debt paid down:
+
+- `scripts/check_legacy_debt.mjs` (part of `npm run lint`) — fails if a
+  disallowed root-level Python module reappears, or if any source tree imports
+  a removed root shim.
+- `tests/unit/test_legacy_root_shims.py` — asserts removed shims stay
+  unimportable, canonical replacements import, and the registry in
+  `latticeai.core.legacy_compatibility` matches reality.
+
+## Root Module Map (removed in 9.9.1)
+
+| Removed root module | Canonical import |
+| --- | --- |
+| `knowledge_graph.py` | `from lattice_brain.graph.store import KnowledgeGraphStore` |
+| `knowledge_graph_api.py` | `from latticeai.api.knowledge_graph import create_knowledge_graph_router` |
+| `kg_schema.py` | `from lattice_brain.graph.schema import ...` |
+| `auto_setup.py` | `from latticeai.setup.auto_setup import probe, recommend` |
+| `llm_router.py` | `import latticeai.models.router` |
+| `ltcai_cli.py` | `from latticeai.cli.entrypoint import main` (console script `LTCAI`) |
+| `mcp_registry.py` | `import latticeai.core.mcp_registry` |
+| `local_knowledge_api.py` | `from latticeai.services.local_knowledge import create_local_knowledge_router` |
+| `p_reinforce.py` | `from latticeai.services.p_reinforce import PReinforceGardener` |
+| `telegram_bot.py` | `from latticeai.integrations.telegram_bot import run_bot` |
+| `setup_wizard.py` | `from latticeai.setup.wizard import scan_environment` |
+| `tools/` | `from latticeai.tools import execute_tool` |
+
+The only remaining root module:
+
+| Kept root module | Why it remains |
+| --- | --- |
+| `server.py` | Lazy proxy to `latticeai.server_app`; preserves `uvicorn server:app`, the Docker CMD, and launch scripts without import-time construction |
+
 ## Brain Core extraction readiness
 
-Removing the internal layers gives `lattice_brain` exactly one import surface
-(its physical module paths). Two structural guards keep it extractable as a
-standalone package:
+`lattice_brain` has exactly one import surface (its physical module paths).
+Two structural guards keep it extractable as a standalone package:
 
 - `tests/unit/test_brain_core_isolation.py` — AST guard that fails if any
   `lattice_brain` module imports `latticeai` (the product imports the Brain,
@@ -36,36 +69,6 @@ standalone package:
 - `tests/unit/test_legacy_root_shims.py::test_internal_shim_layers_are_gone`
   — fails if a removed shim path becomes importable again.
 
-## Current Policy
-
-- Keep compatibility shims while public imports or package entrypoints still
-  depend on them.
-- Prefer moving implementation into focused packages before removing a root
-  module.
-- Add deprecation notes before removal.
-- Avoid breaking package users during a minor release.
-- Do not silently remove rollback, backup, restore, or migration paths.
-- Track every remaining shim through `latticeai.core.legacy_compatibility` so
-  release readiness can report owner, replacement, reason, removal phase, and
-  missing files.
-
-## Root Module Map
-
-| Legacy root module | Current home / direction | Why it remains |
-| --- | --- | --- |
-| `knowledge_graph.py` | `lattice_brain.graph` / `lattice_brain.knowledge` | Compatibility for older graph imports and historical tooling |
-| `knowledge_graph_api.py` | `latticeai.api.memory`, `latticeai.api.search`, graph-related API routers | Compatibility for older API import paths |
-| `kg_schema.py` | `lattice_brain` storage/schema modules | Compatibility for graph schema references |
-| `auto_setup.py` | `latticeai.setup.auto_setup` | Thin compatibility shim for zero-config setup probes and historical commands |
-| `llm_router.py` | `latticeai.models.router` | Compatibility for older local model routing imports |
-| `ltcai_cli.py` | package console entrypoint (`ltcai`) | Compatibility for the installed CLI contract |
-| `mcp_registry.py` | `latticeai.core.mcp_registry` and service-backed registries | Compatibility for MCP/skills lookup entrypoints |
-| `local_knowledge_api.py` | `latticeai.services.local_knowledge` | Thin compatibility shim for local folder/file watcher flows |
-| `p_reinforce.py` | gardener/maintenance service direction | Compatibility for existing Brain gardening runtime hooks |
-| `telegram_bot.py` | opt-in integration package or disabled-by-default connector | Compatibility only; Telegram must remain opt-in |
-| `setup_wizard.py` | `latticeai.setup.wizard` | Thin compatibility shim for first-run recommendation calls |
-| `server.py` | lazy proxy to `latticeai.server_app` / `latticeai.app_factory` | Preserves historical `server.app` imports without import-time construction |
-
 ## Inner Shim Layers (removed in 8.8.0)
 
 | Legacy layer | Example module | Replacement import | Status |
@@ -76,14 +79,10 @@ standalone package:
 
 ## Packaging Notes
 
-`pyproject.toml` and `package.json` still include several root modules because
-older installed packages may import them directly. That is intentional for now.
-The long-term target is:
-
-- move implementation into `lattice_brain`, `latticeai.core`, `latticeai.models`,
-  `latticeai.services`, or `latticeai.api`;
-- leave thin shims with docstrings/deprecation warnings;
-- remove a shim only after tests prove no supported entrypoint relies on it.
+`pyproject.toml` ships a single root module (`server`) plus the
+`latticeai.*`/`lattice_brain.*` packages; the npm package mirrors that. The
+console script `LTCAI` targets `latticeai.cli.entrypoint:main` directly, and
+`bin/ltcai.js` spawns `python -m latticeai.cli.entrypoint`.
 
 ## Removal Checklist
 

package/docs/ONBOARDING.md

@@ -1,6 +1,6 @@
 # Lattice AI Onboarding
 
-Current release: **9.8.0 — Honest Knowledge Pipeline**.
+Current release: **9.9.1 — Clean Foundations**.
 
 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