codevira 1.7.1__tar.gz → 2.0.0__tar.gz

{codevira-1.7.1 → codevira-2.0.0}/CHANGELOG.md

@@ -11,6 +11,518 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Planned for v2.1
+
+See [ROADMAP.md](ROADMAP.md#-v21--honest-known-limitations-from-the-rc5-audit-2026-05-13).
+
+- **Multi-language `get_signature` / `get_code`** — wire tree-sitter (already
+  used for graph indexing) into these tools so non-Python projects stop
+  getting "Python-only by design".
+- **`record_decisions_batch` API** — compress 50× ~800 B per-call overhead
+  into one round-trip.
+- **CLI naming clarity** — pick a canonical hierarchy among `init` / `setup` /
+  `register` / `configure`; add a `codevira inspect` umbrella; deprecate one
+  of `--project-dir` (global) / `--project PATH` (per-subcommand) on a
+  v2.1 → v2.2 cycle.
+
+---
+
+## [2.0.0] — 2026-05-14 — First public 2.0 release
+
+The 2.0 release moves codevira from "memory layer for one developer in one IDE" to
+"active guardian for every AI coding tool you use, on every project, on your local
+machine." Five internal iterations (rc1..rc5 in dev tags) plus a same-day public
+release-candidate cycle (`2.0.0rc1`) of dogfood + audit + product-credibility
+work consolidate into 2.0.0. **Full changelog: [RELEASE_NOTES.md](RELEASE_NOTES.md).**
+
+### Added
+
+- **All 10 hero policies** — active guardian engine intercepts every AI tool
+  call (Edit, Write, prompt submit, session start) and routes through
+  registered policies (Decision Lock, Anti-Regression, Scope Contract,
+  Blast-Radius Veto, Cross-Session Consistency, Token Budget, Live Style
+  Enforcement, Decision Replay, Proactive Intent Inference, AI Promotion
+  Score).
+- **`codevira setup`** — one-prompt installer that detects every AI tool
+  on the machine (Claude Code, Cursor, Windsurf, Antigravity, OpenAI Codex,
+  GitHub Copilot, Continue.dev, Aider) and configures all of them at once.
+- **`codevira projects`** — canonical inventory with `tracked / ghost /
+  orphan / stale` classification (`--json` for scripting; `--ghosts-only`
+  pairs with `clean --ghosts`).
+- **`codevira hooks list / uninstall`** — admin commands for Claude Code
+  lifecycle hooks; surgical install + clean removal.
+- **`codevira clean --ghosts`** — surgical removal of incomplete project
+  data dirs without touching tracked projects.
+- **`codevira init --single-language`** — opt-out flag for the new
+  index-everything default.
+- **`codevira engine` subcommand** — internal hook dispatcher; surfaces in
+  `--help` so the lifecycle hooks can call it.
+- **4 new doctor checks** — `claude_mcp_visibility`, `codeindex_freshness`,
+  `semantic_search_health`, `ghost_projects` (total 14 per run).
+- **Per-project config opt-out for cross-session injection** —
+  `.codevira/config.yaml: project: { cross_session_mode: off }` disables
+  the per-prompt context block without touching env vars.
+
+### Changed
+
+- **`codevira init` default** — indexes every common source/config/docs
+  extension (~75 total: `.py`, `.ts`, `.go`, `.yaml`, `.toml`, `.md`,
+  `.html`, `.sql`, `.proto`, …) instead of narrowing to one language.
+- **`codevira agents` default** — renders nudge files for **detected** IDEs
+  only; `--ide=all` opt-in for the legacy "render for every supported IDE"
+  behavior.
+- **`codevira doctor`** — now genuinely read-only; snapshots the projects
+  dir at entry and removes any new dirs at exit.
+- **`search_codebase`** — graceful structural fallback (filename + symbol
+  substring) when the semantic index is unavailable, with the correct
+  `fix_command` instead of a misleading "reinstall codevira" hint.
+- **`get_node` / `get_impact` / `query_graph`** — three-case error
+  differentiation: "no graph DB" / "graph empty" / "file not in populated
+  graph", each with its own `fix_command`.
+- **`get_decision_confidence`** — exposes `decisions_in_db_total` and
+  `decisions_eligible_for_outcomes` plus a four-state interpretation so
+  users understand WHY their `total_decisions` may be zero. Outcome
+  tracker also classifies file-less decisions via mention-extraction.
+- **Playbooks** — project-scoped first
+  (`<data_dir>/playbooks/` or `<project>/.codevira/playbooks/`); bundled
+  Python defaults are skipped with a clear warning when project language
+  ≠ Python.
+- **`register_project`** uses `ON CONFLICT … COALESCE(excluded.git_remote,
+  projects.git_remote)` — subsequent registrations can't silently clear
+  the `git_remote` column.
+- **Auto-init self-heal** runs SYNCHRONOUSLY in the calling thread of every
+  CLI invocation — daemon thread death no longer leaves ghost data dirs.
+- **Default install** includes ChromaDB + sentence-transformers (no
+  `[search]` extra needed for semantic search).
+- **README "92% reduction" claim** qualified with honest scope, per-prompt
+  cost, and amortization curve.
+- **`register` deprecation** now names the removal version (v2.1).
+
+### Fixed
+
+- macOS Apple Silicon **fork-safety segfault on first `codevira index`**
+  (auto-applied at indexer import).
+- **Setup interactive prompt** silent-fail on unexpected input — replaced
+  with a shared `_prompts.confirm` helper that retries, flushes stdout,
+  and handles `KeyboardInterrupt` cleanly.
+- Three **`status --global` UI typos** that always rendered 0/0/0
+  regardless of actual `global.db` state.
+- Four **FK race conditions** in the watcher pipeline.
+- **Python `None` leaked into argparse choices** for `agents --ide` and
+  `budget` positional.
+- Several **silent argument clamps** in `replay --since`, `insights --since`,
+  and `insights --top` now print visible warnings.
+
+### Tests
+
+- 2395 / 2395 passing (deterministic).
+- ~1091 net new tests since v1.8.0 (mostly from the v2.0 hero policies +
+  audit-driven regression coverage).
+
+### Note on internal v1.8.1 + 2.0.0rc1
+
+A v1.8.1 production hotfix existed in dev tags but was never published to
+PyPI; its fixes are folded into 2.0.0. A `2.0.0rc1` was briefly published
+on PyPI (2026-05-14) as a same-day public release candidate; the code is
+identical to 2.0.0. Anyone who installed `codevira==2.0.0rc1` can
+`pipx install --upgrade codevira` to move to 2.0.0 final.
+
+---
+
+## [Original v1.9 plan, deferred]
+
+- **Interactive checkbox UI for `codevira configure`**. The current
+  prompt asks users to type comma-separated indices ("1,3,5") into a
+  numbered list — fine for 3–5 items, awkward for 15+. v1.9 will add
+  arrow-key navigation + space-to-toggle multi-select, matching the
+  UX of `npm create vite`, `gh repo create`, etc.
+
+  **Design (opt-in dependency):**
+  - Default install (`pip install codevira`) keeps the current numbered
+    prompt — zero new dependencies, zero new failure modes.
+  - `pip install codevira[ui]` pulls `questionary` (~3 MB). When
+    importable AND `sys.stdin.isatty()` AND `os.environ.get("TERM")
+    != "dumb"`, `prompt_multi_select` switches to the checkbox UI.
+  - `--dirs` and `--extensions` flags continue to work for both paths
+    (CI / scripts / non-interactive use).
+
+  **Why deferred from v1.8.1:** v1.8.1 is a pure crash hotfix; mixing
+  in a UX feature would slow the release and complicate testing. The
+  numbered prompt has shipped since v1.8.0 and works fine — this is
+  polish, not a fix.
+
+  **Implementation notes for whoever picks this up:**
+  - Site: `mcp_server/cli_configure.py:prompt_multi_select` (line ~176)
+  - Add `[ui]` extra in `pyproject.toml` with `questionary>=2.0`
+  - TTY detection already exists (`NonInteractiveError` raised on
+    `not sys.stdin.isatty()`); extend it to also branch on
+    questionary availability
+  - Test surface: split into two test classes — one mocks `input()`
+    (current behavior), one mocks `questionary.checkbox()`. Skip the
+    questionary tests when not installed.
+  - Accessibility: keep the numbered prompt for screen-reader users;
+    document `CODEVIRA_DISABLE_TUI=1` env var as the override.
+  - No schema changes, no public-API changes.
+
+### Other v1.9 candidates (no design yet)
+
+- Watcher restart circuit breaker (deferred from v1.8.1 — see "Out of
+  scope" below).
+- Refactor `_enable_wal_with_retry` into a shared `indexer/_sqlite_util.py`
+  (deferred from v1.8.1).
+- Watcher hot-reload of `config.yaml` on disk changes.
+- `crash_logger` size cap or rotation (currently grows unbounded).
+
+---
+
+## [1.8.1] — 2026-05-02 — Production Hotfix from Real-World Crash Logs
+
+Pure bug-fix release. No new features, no schema changes, no public-API
+changes. Motivated by a real production failure on the maintainer's
+machine: **43 crashes in 70 minutes** logged by `crash_logger` between
+07:37 and 08:47 on 2026-04-24, all under
+`WHERE: background watcher: incremental reindex`.
+
+Breakdown:
+- **41 × `InterruptedError` (EINTR, errno 4)** in
+  `_get_changed_files`'s rglob walk, all walking
+  `~/Library/Group Containers/...` (WhatsApp, Office, etc.) and
+  `~/Library/Containers/...` (TextEdit, mediaanalysisd, …).
+- **2 × `OperationalError("database is locked")`** in
+  `SQLiteGraph.add_symbol` and `remove_symbols_for_file`.
+
+Root cause: a rogue project data dir with
+`metadata.json.original_path = "/Users/sachin"` (the user's `$HOME`).
+`auto_detect_project` saw `Library`, `Downloads`, `Documents`, `go` as
+"subdirs", and the watcher then walked huge unrelated trees. v1.8.0's
+bootstrap (`cmd_configure`, `auto_init`) didn't refuse `$HOME`, and
+neither did `cmd_init`.
+
+### Fixed
+
+- **Refuse `$HOME` and system top-levels as a project root** (the
+  critical fix — eliminates 41 of the 43 production crashes by
+  preventing the rogue project from forming). New helper
+  `mcp_server.paths.is_invalid_project_root()` rejects `$HOME`, `/`,
+  `/Users`, `/home`, `/tmp`, `/private/tmp`, `/var`, `/private/var`,
+  `/etc`, `/opt` (plus the macOS-resolved `/private/etc` and
+  `/System/Volumes/Data/home` forms). Wired into TEN distinct sites
+  covering every state-creating path the codebase exposes:
+  - **CLI entry points (6):** `cmd_configure`, `cmd_init`, `cmd_index`,
+    `cmd_register`, `cmd_serve` (refuses both regular serve AND
+    `--install-service`; `--uninstall-service` is exempt so users can
+    always remove old launchd plists), `auto_init._run_background_init`.
+  - **MCP server entry points (2):** `mcp_server.server.main()` (stdio
+    transport) and `mcp_server.http_server.run_http_server()` (HTTP
+    transport). Both are reachable directly via `python -m`, not just
+    through the CLI.
+  - **Direct module entry (1):** `indexer.index_codebase.__main__`
+    (`python -m indexer.index_codebase --full | --watch | (default)`)
+    — this is a separate CLI surface from the `codevira` binary;
+    pre-revalidation it bypassed `cli.cmd_index`'s guard entirely.
+    `--status` is exempt (read-only, bails on missing graph.db).
+  - **Defense-in-depth (1):** `indexer.index_codebase.start_background_watcher`
+    refuses to start the watcher even if a programmatic caller bypasses
+    every entry-point guard above. Returns `None`; both `cmd_watch` and
+    `server.main` handle `None` correctly.
+
+  The `server.main()` and `run_http_server` guards are the most critical
+  — without them, a user upgrading from v1.8.0 *without* first running
+  `clean --orphans` would still hit the original crash mode: their
+  leftover rogue `config.yaml` would drive `start_background_watcher`
+  into walking `~/Library/Group Containers/...`, which is exactly where
+  the 41 production `InterruptedError` crashes came from. The
+  `start_background_watcher` defense-in-depth guard is a belt-and-braces
+  fallback — even if all entry-point guards regressed, the watcher
+  itself cannot start with an invalid project root.
+
+  `cmd_index`, `cmd_register`, `cmd_serve --install-service` close
+  defense-in-depth holes that pre-revalidation could have leaked state
+  on disk: silent dead-weight `mkdir` of
+  `~/.codevira/projects/<HOME_slug>/{graph,codeindex}/`, IDE configs
+  pinned to broken paths, and persistent launchd plists pointing at
+  `$HOME`. Pre-release revalidation across three rounds walked every
+  CLI sub-command, the stdio/HTTP server entry, the launchd
+  `--install-service` path, the `start_background_watcher` direct call
+  path, and the production-replay scenario (synthetic v1.8.0 leftover
+  rogue + `codevira` from `$HOME`). All paths refuse cleanly with zero
+  new crashes; legitimate projects untouched.
+
+  `auto_init` sets `_progress["status"] = "error"` so the MCP server
+  stops looping on retries.
+
+- **`SQLiteGraph` WAL with retry — port of the v1.8.0 GlobalDB fix**
+  (eliminates the 2 of 43 `database is locked` crashes). v1.8.0 fixed
+  the same race for `GlobalDB` after round 3 of binocular review;
+  `SQLiteGraph` was missed. `__init__` now opens with `timeout=30`,
+  enables WAL via the same retry loop pattern, and sets
+  `PRAGMA busy_timeout=30000` for subsequent writes.
+
+- **`_get_changed_files` and `cmd_full_rebuild` rglob loops tolerate
+  `OSError`** (defense-in-depth — even on legitimate projects,
+  transient `EINTR`, `PermissionError`, or "directory changed during
+  iteration" should not kill the whole reindex). Per-watch-dir scope
+  matches `watchdog.Observer`'s thread-per-watch model: the
+  microsecond-spaced parallel-thread crashes (3 within 6μs at
+  08:15:29 and 08:26:04 in the production log) confirm this is the
+  right granularity. `InterruptedError` is a subclass of `OSError`, so
+  the broader catch covers EINTR plus other transient walk failures.
+
+### Added
+
+- **`codevira clean --orphans`** — recovery path for users already hit
+  by the `$HOME`-bootstrap bug on v1.8.0. Walks
+  `~/.codevira/projects/*/metadata.json`; for each entry whose
+  `original_path` is rejected by `is_invalid_project_root()` OR no
+  longer exists on disk, removes the data dir and deletes the matching
+  row from `~/.codevira/global.db`. Reuses the existing `--dry-run`
+  and `-y/--yes` flags. Without this, affected users would need to
+  `rm -rf` and run raw sqlite by hand.
+
+- **Denylist macOS/Linux/cloud-sync user-data dirs in
+  `auto_detect_project`** (defense-in-depth). `_SKIP_DIRS` extended
+  with `Library`, `Downloads`, `Music`, `Movies`, `Pictures`,
+  `Desktop`, `Public`, `Applications`, `Videos`, `Templates`, plus
+  cloud-sync top-levels (`Dropbox`, `iCloud Drive`, `OneDrive`,
+  `Google Drive`, `Box`). Even if `is_invalid_project_root` somehow
+  misses (e.g. a user passes `--project-dir` to a `$HOME`-shaped
+  layout), these never show up in `watched_dirs`. A user who
+  legitimately has a project named e.g. `Library` can still pass
+  `codevira configure --dirs Library` to opt in.
+
+### Out of scope (deferred to v1.9)
+
+- **Watcher restart circuit breaker.** Crash log shows ~60s gaps
+  between EINTR crashes — no backoff. Adding a circuit breaker is real
+  design work; the rglob `OSError` tolerance closes the immediate
+  hole.
+- **Refactoring `_enable_wal_with_retry` to a shared util.** 25 lines
+  of duplication for one patch cycle is the right call; touching
+  `GlobalDB`'s tested-in-v1.8.0 code is higher risk.
+- **`crash_logger` size cap or rotation.** Log file is ~97KB now; will
+  grow unbounded over time. Out of scope for hotfix; flagged for v1.9.
+
+---
+
+## [1.8.0] — 2026-04-23 — Memory Sharpening + Config UX
+
+Three internal improvements that make the memory we already capture **sharper**,
+without making it heavier. Zero new MCP tools. Zero new tables. The public API
+shape changes only one thing: `get_session_context()` gains a `focus_source`
+field (~10 tokens, additive, backwards-compatible).
+
+The problem this release solves:
+- `get_session_context()` returned the 3 newest decisions by timestamp —
+  regardless of whether they had anything to do with the current task.
+- `search_decisions()` ordered purely by recency — a `file_path` match
+  was no better than a match buried in an unrelated session summary.
+- `log_session()` inserted every decision unconditionally — a day of
+  iterative agent work logged the same intent 5+ times.
+
+### Fixed
+
+- **MCP `serverInfo.version` reported the MCP library version, not codevira's**
+  (pre-existing bug, surfaced during v1.8 install verification on Python
+  3.13). `Server("codevira")` was constructed without a `version=` argument,
+  so the framework defaulted to its own pip-package version (e.g. `1.27.0`)
+  in the JSON-RPC `initialize` handshake response. Clients use this field
+  for telemetry and version gating, so the wrong value misled them.
+  One-line fix: `Server("codevira", version=__version__)`.
+- **`get_session_context()` read the wrong dict key** (pre-existing bug).
+  `list_open_changesets()` returns `{"open_changesets": [...], ...}`, but
+  `get_session_context` looked for `"changesets"`. The `open_changesets`
+  field in the session-context response was **always empty** in production.
+  Tests didn't catch it because mocks used the same wrong key.
+
+- **`GlobalDB` concurrent-open race condition** (pre-existing bug — latent
+  since v1.6's centralized storage introduced shared `~/.codevira/global.db`).
+  `PRAGMA journal_mode=WAL` requires an exclusive lock and — unlike normal
+  SQL — does NOT honour `sqlite3`'s `busy_timeout`. When multiple processes
+  or threads opened the same fresh database concurrently (e.g. several
+  projects' first-ever `codevira register` running in parallel, or the
+  `global_sync` background export racing the MCP server thread), one or
+  more would raise `OperationalError('database is locked')` and silently
+  fail to register. The test `test_concurrent_access_from_threads` was
+  flaky at 60% failure rate, hinting at the real issue. Fixed with WAL-
+  enable retry loop + short-circuit when WAL is already active. Stability
+  verified at 20/20 passes across 20 test runs.
+
+### Changed
+
+- **Focus-weighted `recent_decisions` in `get_session_context()`**. Instead
+  of chronological "newest 3", decisions are now ranked by what the agent
+  is currently focused on:
+  1. Open changeset with `files_pending` → focus = first file path of the
+     most-recently-created changeset.
+  2. Strong `current_phase.next_action` signal → focus = extracted keywords
+     (rejects short or stop-list-only actions like "continue work").
+  3. Otherwise → chronological fallback (unchanged behaviour).
+  If focus returns fewer than 3, the list pads with `get_recent_decisions()`.
+  New response field `focus_source` (`"open_changeset:<id>"`, `"next_action"`,
+  or `null`) lets the agent see *why* it got these decisions.
+
+- **Smarter `search_decisions()` ranking**. SQL now adds `file_path` to both
+  the WHERE clause and a CASE-based ORDER BY:
+  `file_path match (0) > decision text (1) > context (2) > summary-only (3)`,
+  then newest first within each tier. Searching for `"src/auth.py"` now
+  surfaces file-path matches even when the decision text doesn't mention
+  the path.
+
+- **Decision dedup on write**. `log_session()` now skips a new decision
+  if it has a `file_path` and its token-set overlaps ≥ 80% with any of
+  the 5 most recent decisions for that same file. The session row is
+  always created; only redundant *decisions* are dropped. Short
+  decisions (< 3 tokens) and decisions without `file_path` are always
+  inserted.
+
+### Added
+
+- `focus_source` field on `get_session_context()` response (≈10 tokens).
+- `mcp_server.tools.learning._infer_focus()` — pure helper, module-private.
+- `indexer.sqlite_graph._is_duplicate()` — pure token-overlap helper,
+  module-private, independently testable.
+- **`codevira configure`** — new CLI subcommand. Scans your project
+  (gitignore-aware via existing `discover_source_files()`), shows discovered
+  directories and file extensions with counts, lets you pick via a numbered-
+  list prompt, writes the choices back to `.codevira/config.yaml`, and offers
+  to rebuild the index. Non-interactive:
+  `codevira configure --dirs src,lib --extensions .py,.ts --no-reindex`.
+  Solves the AgentStore-style "0 chunks indexed" case where
+  `auto_detect_project()` mis-guesses a monorepo layout.
+  When `config.yaml` is missing (normal state after `codevira register` but
+  before the first MCP tool call), `configure` auto-bootstraps it in full
+  parity with `auto_init`'s first-init path: writes `metadata.json` (rename-
+  resilient lookup via `git_remote`) and registers the project in
+  `~/.codevira/global.db` for cross-project intelligence. Missing these on
+  earlier drafts would have left the project invisible to rename-resilient
+  path lookup and absent from global memory until the first session log.
+- **Zero-chunks safety hint at index time.** When `codevira index --full` or
+  `codevira index` (incremental, project-wide) matches no files against your
+  `watched_dirs` + `file_extensions`, the indexer now prints a one-line
+  remedy pointing at `codevira configure`. Output goes to **stderr** (not
+  stdout) so the hint never leaks into the MCP JSON-RPC wire when
+  `start_background_full_index` runs during auto_init inside the MCP server
+  process. Also logged at WARNING level so background invocations
+  (auto-init, launchd watcher) leave a trace regardless of terminal
+  capture. Does NOT fire for caller-scoped incremental runs (e.g. the
+  `refresh_index` MCP tool targeting a specific file) — zero matches there
+  is the caller's choice, not a misconfiguration.
+- `codevira register` success banner now nudges toward `codevira configure`.
+
+### Internal
+
+- 87 new tests:
+  - 34 for v1.8 memory sharpening (focus inference priority rules, ranking
+    tier ordering, dedup threshold behaviour, session-row-always-created
+    invariant, NULL file_path fallback, session_id filtering + new ranking SQL)
+  - 43 for `codevira configure` (scan_project with centralized-mode
+    decoupling + skip_dirs honoring, multi-select prompt incl. non-TTY
+    fallback + Ctrl+C clean-abort, config writer preserve/dedupe/idempotency,
+    orchestrator edge cases incl. bootstrap on missing config, dry-run disk
+    safety, corrupt-YAML handling, empty-extensions safety, PermissionError
+    friendly wrapper, `--dirs`/`--extensions` normalization)
+  - 10 for the zero-chunks hint (unit tests of the helper proving it writes
+    to stderr not stdout + integration tests proving it fires ONLY for full
+    or project-wide-incremental scans, not caller-scoped or normal "no files
+    changed")
+- Full test suite: **1,398 passing, 0 deterministic failures** (up from
+  1,306 at v1.7.1 → +92). The two "pre-existing watchdog failures" that
+  haunted earlier drafts of this CHANGELOG turned out to be an environment
+  issue in a single dev machine (system Python 3.9 without `watchdog`);
+  the pipx-installed v1.8.0 environment has all required deps. The one
+  pre-existing flaky test (`test_concurrent_access_from_threads`) is now
+  fixed by the `GlobalDB` WAL-enable retry loop described above.
+
+### Verified environments
+
+- **macOS (APFS)** + Python 3.9 system + Python 3.11 pipx: full regression
+  passes; all interactive + non-interactive flows manually verified on three
+  real projects (AgentStore, UDAP, ToolsConnector).
+- **Cross-process + thread concurrency**: stress-tested (12 threads × 20
+  writes, 8 subprocesses × 25 writes, 100 concurrent-read/write cycles) —
+  0 errors, 0 data loss.
+
+### Unverified environments / known gaps (candidates for v1.8.1 or v1.9)
+
+- **Windows**: `os.replace` atomicity weakens when the destination is open
+  by another process. If a Windows user has Claude Code reading
+  `config.yaml` at the moment `codevira configure` writes it, the write
+  may fail with `PermissionError`. Pre-existing risk; v1.8 does not fix
+  and does not regress. Windows smoke-testing is a v1.9 scope item.
+- **Network filesystems (NFS, SMB)**: atomic-replace guarantees are weaker
+  on network FS. Unlikely in solo-dev environments (codevira's target);
+  possible in enterprise setups.
+- **Python 3.10, 3.12**: The APIs `codevira configure` uses are stable
+  across 3.10+. Syntax-verified against 3.10+. **Python 3.13.7
+  empirically verified** during v1.8 install validation (full pipx
+  install + MCP handshake working). 3.10 and 3.12 are syntax-verified
+  only. CI on all Python versions is a v1.8.x task.
+- **Case-insensitive filesystem slugs**: On macOS APFS (default), paths
+  differing only in case (`~/Documents` vs `~/documents`) produce
+  different slugs for the same physical directory, creating split state.
+  Pre-existing since v1.5 — fixing requires a migration step for existing
+  users and is scoped to v1.9.
+- **Interactive TTY automated coverage**: The interactive prompt flow is
+  tested via mocked stdin + `sys.stdin.isatty`. A real terminal session
+  was manually verified during development; automated TTY testing (via
+  pexpect or similar) is a v1.8.x nice-to-have.
+- **MCP client post-upgrade reload**: `codevira register` writes config;
+  each MCP client (Claude Code, Cursor, Windsurf, Antigravity, Claude
+  Desktop) needs to reload to see changes. Verified for Claude Code.
+  Other clients may have edge cases that surface post-release.
+
+### Known test flake (NOT v1.8; pre-existing)
+
+- `test_chunk_error_continues_to_next_file` fails ~3/10 times in the full
+  suite on Python 3.9 (system) due to a chromadb+pydantic version
+  incompatibility raising `TypeError` during `import chromadb`, which
+  `_check_search_deps()` doesn't catch (it only catches `ImportError`).
+  **Not introduced by v1.8 and not touched by v1.8 code paths** — verified
+  by measuring the same 3/10 flake rate on clean v1.7.1. v1.8 deliberately
+  does not widen the exception catch because it would silently mask real
+  dep issues; a proper fix belongs in a targeted follow-up PR with its own
+  test coverage. Does not affect production users — the condition requires
+  a specific dev environment (Py 3.9 + mismatched chromadb/pydantic).
+- Regression guards added by the binocular review pass:
+  - `test_centralized_mode_data_dir_and_project_root_decoupled` — catches
+    the production bug where `data_dir.parent` was used where
+    `get_project_root()` was required (centralized mode v1.6+).
+  - `test_bootstraps_config_when_missing` — catches the workflow where
+    `codevira register` was run but config.yaml hasn't been written yet
+    (auto_init hadn't fired because no MCP tool call had happened).
+  - `test_bootstrap_respects_dry_run` — catches bootstrap writing disk
+    during `--dry-run`.
+  - `test_fires_on_stderr_when_not_quiet` — catches zero-chunks hint
+    leaking to stdout, which would corrupt the MCP JSON-RPC wire in stdio
+    mode.
+  - `test_empty_extensions_non_interactive_errors_exit_2` — catches
+    `--extensions ""` being silently accepted, which would write an empty
+    `file_extensions: []` and re-create the zero-chunks bug.
+  - `test_ctrl_c_in_prompt_returns_exit_0` — catches KeyboardInterrupt
+    propagating a traceback to the user.
+  - `test_permission_error_on_write_exits_1` — catches PermissionError /
+    OSError propagating a traceback when config.yaml isn't writable.
+  - `test_honors_user_skip_dirs_from_config` — catches scan_project
+    ignoring the user's explicit skip_dirs in config.yaml.
+
+### Known limitations
+
+- A running file-watcher or live MCP server session won't pick up config
+  changes until it restarts (the watcher snapshots `watched_dirs` at boot).
+  Restart your AI tool after `codevira configure` to apply changes.
+- `yaml.safe_dump` doesn't preserve comments in `config.yaml`. First-time
+  configs are auto-generated and have no comments; users who hand-edited
+  may see formatting normalized after `codevira configure` rewrites the file.
+
+### Unchanged (intentionally)
+
+- No new MCP tools. No new tables. No schema migration.
+- `search_decisions()` method signature unchanged.
+- `log_session()` method signature unchanged.
+- `get_session_context()` keys are additive — no removals.
+- `auto_init.py`, `detect.py`, `gitignore.py`, and `metadata.json` writer
+  untouched; `codevira configure` reuses all existing detection machinery.
+
 ---
 
 ## [1.7.1] — 2026-04-22 — Search Timeout Fix & Version Display