feat(directives): harvest 8 directives from feature_flags/RAG/cache/knowledge styleguides + 4 new styleguides

This commit is contained in:
ed
2026-07-02 22:17:20 -04:00
parent 09d6a9c7c8
commit cdc0f1405c
8 changed files with 436 additions and 0 deletions
@@ -0,0 +1,72 @@
# chroma_cache_path — v1
**Why this iteration:** Lifted verbatim from `conductor/code_styleguides/chroma_cache.md` §"The Rule" + §"The Pre-Cleanup Pattern" (lines 5-50). This is the baseline encoding — the rule-plus-rationale-plus-anti-patterns style currently in production.
Future variants will test alternative encodings (rule-only, before/after) against this baseline.
**Source:** `conductor/code_styleguides/chroma_cache.md:5-50`
---
# Chroma Cache Path Styleguide
## The Rule
The ChromaDB persistent vector cache lives at:
```
<project_root>/tests/artifacts/.slop_cache/chroma_<collection_name>/
```
**NOT** at the per-run `tests/artifacts/live_gui_workspace_<timestamp>/` subdir.
Tests that interact with RAG **MUST** pre-clean the cache to avoid persistent state from prior tests in the batched run.
## Why This Rule Exists
The chroma cache path is auto-derived from `RAGEngine._init_vector_store()` (`src/rag_engine.py:108-125`):
```python
db_path = os.path.abspath(os.path.join(
self.base_dir, ".slop_cache", f"chroma_{vs_config.collection_name}"
))
```
`self.base_dir` is computed as `Path(active_project_path).parent`. **The trailing-slash bug**: when the test config produces a project path ending in `/` (e.g., from `os.path.join` with a trailing `/`), `Path(p).parent` returns the directory ONE LEVEL HIGHER than expected. So the chroma cache lands at `tests/artifacts/.slop_cache/` (the parent of the per-run `live_gui_workspace_<timestamp>/` subdir) instead of inside the per-run subdir.
## The Pre-Cleanup Pattern
RAG tests should wipe the chroma cache BEFORE pushing RAG config. The pattern is in `tests/test_rag_phase4_final_verify.py`:
```python
from pathlib import Path
import shutil
def test_phase4_final_verify(live_gui):
# Wipe any stale chroma from prior batched runs
cache = Path("tests/artifacts/.slop_cache/chroma_test_final_verify")
if cache.exists():
shutil.rmtree(cache, ignore_errors=True)
# ... rest of test
```
`ignore_errors=True` is required because:
- On Windows, the chroma client may still hold file handles; `rmtree` may fail with `WinError 32` (sharing violation).
- If a parallel xdist worker is mid-write, the rmtree can race; `ignore_errors` lets the next worker's write retry.
## Anti-Patterns
**Assuming the cache is per-run:**
```python
def test_rag(live_gui, live_gui_workspace):
# WRONG: live_gui_workspace is a per-run subdir, but the chroma
# cache is at tests/artifacts/.slop_cache/, NOT under live_gui_workspace
cache = live_gui_workspace / ".slop_cache" / "chroma_test"
if cache.exists():
shutil.rmtree(cache) # Doesn't find the actual cache
```
**Not pre-cleaning at all:**
```python
def test_rag(live_gui):
# WRONG: no pre-cleanup. If a prior batched run with a different